Troubleshooting
This page covers messages DarkRay shows itself. When a message points at something deeper, open the
Console with View › Panels › Console (F9 by default). It shows the app’s log, which is also
saved in ~/.darkray/logs/darkray.log.
A catalog won’t open
Section titled “A catalog won’t open”If a catalog can’t be opened at startup, DarkRay opens your other catalogs, or a default one, and shows Catalog Not Opened: “The catalog “name” could not be opened. The file is missing.” Choose:
- Locate… to find the catalog file, if it was moved or renamed, and open it.
- Remove to take it off Open Recent. No file is touched.
- Not Now to leave it on Open Recent, marked “(missing)”.
When you open a catalog yourself with File › Open Catalog…, you may see:
| Message | What it means |
|---|---|
| “The catalog file no longer exists” | The file was moved or deleted. Open it from its new place with Open Catalog…. |
| “Can’t open name.db: it was made by a newer DarkRay (catalog version N; this one reads up to M).” | Update DarkRay. Nothing in the file was changed. |
| “Can’t open name.db: it isn’t a DarkRay catalog (it holds another program’s tables).” | The file is a different program’s database. Nothing in it was changed. |
| “Could not open catalog:” followed by an error | Open the Console for the details. |
New Catalog… refuses a name with spaces or any of < > : " / \ | ? *, and a name that is
already taken (“A catalog named ‘x’ already exists.”).
Photos or folders are missing
Section titled “Photos or folders are missing”A photo whose file DarkRay can’t find shows a warning badge: “Source file missing: the original can’t be found on disk”. A folder that is gone shows a warning icon, and hovering it says “Offline: not found at …”. Missing Photos appears under Library in the left panel only while something is missing.
- One photo: right-click it, or use Image, and choose Locate Missing Photo…. Pick the file. Other missing photos in the same folder are found too, and the status bar reads “Photo located; 12 more found nearby”. If the file’s contents differ from the one that was catalogued, DarkRay says so and keeps your edits.
- A whole folder: right-click the folder in the Folders panel and choose Locate Folder…. The status bar reads “Folder relocated: 140 photos re-pointed” and adds “; 2 still missing” if some are.
See Library for folders and files.
“Preparing image…”
Section titled ““Preparing image…””A RAW whose RAW Process settings ask for denoise is prepared before you can edit it. The photo stays on screen under a banner:
| Banner | Meaning |
|---|---|
| “Preparing image…” or “Preparing image… 42%” | Working. Cancel stops it; the photo can’t be edited until it is prepared. |
| “Preparing image… waiting for the GPU (…)” | Another job holds the GPU. It starts when that one ends. |
| “Couldn’t prepare this image: …” | It failed, with the reason. Click Retry. |
| “Image not prepared” | You cancelled. Click Retry. |
Preparing can take a while. Once a photo is prepared, the result is kept. See Editing for RAW Process.
The GPU isn’t used
Section titled “The GPU isn’t used”DarkRay uses an NVIDIA GPU through CUDA when it finds one, and otherwise runs the same steps on the CPU, which is slower. To see which it chose, look in the Console at startup:
- “GPU available: …”, followed by the card’s name and memory, means the GPU is in use.
- “CUDA device detected but initialization failed” means a card was found but would not start. The Console log that follows has the error.
- “Preference use_gpu=‘on’ but no CUDA device available — falling back to CPU.” means you asked for the GPU and there is none.
- “Preference use_gpu=‘off’ — GPU path disabled by user setting.” means it is turned off.
The setting is Preferences › Edit › GPU compute (Auto, On or Off) and needs a restart. Off also stops AI models from using the GPU. See Library, Import and Edit preferences.
An AI mask or depth map isn’t available
Section titled “An AI mask or depth map isn’t available”The status bar names what is missing:
| Message | What to do |
|---|---|
| “AI unavailable: install torch (see requirements.txt)” | The AI libraries are not installed in DarkRay’s environment. |
| “Subject unavailable: run scripts/fetch_models.py” | The Subject model’s weights are not downloaded. |
| “Sky unavailable: run scripts/fetch_models.py (SAM 3 also needs transformers≥5)” | The Sky model’s weights are not downloaded. |
| “Select unavailable: needs SAM 3 weights + transformers≥5” | The weights for Select, which finds a named thing in the photo, are missing. |
| “Depth needs torch + transformers” | The AI libraries are not installed. |
| “Depth: the depth model’s file is missing (Preferences › AI Models)” | The depth model you added has moved, or its network share is offline. Edit it in Preferences › AI Models to point at the file again, or choose another depth model. |
To download the weights, run scripts/fetch_models.py from DarkRay’s folder with the Python in
its .venv folder. To keep them elsewhere, set the DARKRAY_MODEL_DIR environment variable to
that folder. Preferences › AI Models shows whether each feature’s model is ready. See
RAW and AI model preferences.
If a photo has an AI mask whose image was cleared from the cache, DarkRay asks about Missing AI Masks and offers Regenerate. Until you do, that layer has no effect.
An assistant can’t connect
Section titled “An assistant can’t connect”An AI assistant or a Python script reaches DarkRay through MCP. These messages come from the connection:
| Message | What to do |
|---|---|
| “DarkRay isn’t running; start it.” | Start DarkRay. |
| “Assistant control is off: in DarkRay, click MCP at the right end of the status bar.” | Click the MCP button in the status bar. Ready appears beside it. |
| “DarkRay closed the connection; try again.” | Run the request again. |
| “DarkRay didn’t answer within N s.” | Try again. |
To have MCP on at every launch, turn on Preferences › General › Turn MCP on at launch. See Scripting & MCP.
A merge or export stops
Section titled “A merge or export stops”| Message | What to do |
|---|---|
| “Another merge is running; try again when it ends.” | Wait, or cancel the merge in the status bar. Only one runs at a time. |
| “These photos aren’t all the same size (…).” | Merge only frames from one camera at one size and orientation. |
| “Fewer than two of these photos overlap enough to stitch…” | Add frames, or drop ones that don’t overlap by about a third. See Merge a panorama. |
| “name.exr was written but could not be cataloged” | The merged file is on disk, but the catalog did not take it. The reason follows the message. |
| “Choose a folder that exists” | Pick an existing folder in the Export dialog. |
| “Several photos need {name} or {n} in the name, or they would share one file” | Add a token to the file name. See Export photos. |
Merge and export results are listed in Merge photos and Export photos.