Skip to content

Troubleshooting

Jump to bottom
github-actions[bot] edited this page Aug 19, 2026 · 9 revisions

Troubleshooting

Tips and solutions for common issues when running LrGeniusAI.

GUI Error Reporting

LrGeniusAI surfaces errors directly in Lightroom rather than hiding them in log files. If something fails during a batch task, a Task Completion Dialog shows which photos succeeded, which failed, and why. For more persistent errors, check the log file via Plug-in Manager → Show logfile or Copy logs to desktop.

Common Issues

1. Installer & Security Warnings (SmartScreen / Gatekeeper)

Since LrGeniusAI installers are not currently code-signed, your OS may block them.

  • Symptom: "Windows protected your PC" or "LrGeniusAI.pkg cannot be opened because it is from an unidentified developer".
  • Resolution: Refer to the Getting Started guide for OS-specific bypass steps. This is a one-time requirement during installation.

2. Plugin/Backend Version Mismatch

Using a newer plugin with an older backend (or vice versa) causes API errors.

  • Symptom: Errors like "Failed to initialize database", "API request failed", or unexpected 500 errors immediately after an update.
  • Resolution: Make sure both the plugin (.lrdevplugin) and the backend server are updated to the same release version. Download both from the same GitHub release. If you updated the plugin only, re-run the backend installer from the same release.

3. On-Device AI Models Missing or Not Downloading

Two features run their own model on the backend machine: smart photo search (SigLIP2) and species identification (BioCLIP 2). Neither model ships with the installer — you fetch them once from Plug-in Manager → LrGeniusAI → On-device AI models → Download AI models, which is also where their readiness is reported. Roughly 3 GB in total.

  • Symptom: Enable smart photo search or Identify animal and plant species is greyed out in the Analyze & Index dialog, an indicator under On-device AI models stays red, or indexing reports species: model not downloaded.
  • Resolution:
    1. Click Download AI models and leave the progress bar running. It fetches only what is missing, so it is safe to press again after a failed attempt — an existing installation that already has the search model will only download the species one.
    2. Check your internet connection on the machine running the backend, not the one running Lightroom. If they are different machines, the models must be downloaded on the server.
    3. Make sure the backend has write permission to its model cache: ~/.cache/lrgenius/models/, or %USERPROFILE%\.cache\lrgenius\models\ on Windows. It is the home directory of the account the backend runs as, which is not necessarily yours if you installed it as a service.
    4. If a download fails part-way, the error is reported verbatim in the Lightroom dialog and in the backend log — worth reading before retrying, since a 404 means the release assets could not be reached rather than anything wrong with your setup.
    5. If an indicator stays red after a download that reported success, restart the backend so it re-checks the files on disk.

Face detection is fetched by the same button as everything else. It was not always: until the pipeline moved to YuNet + FaceNet, it ran InsightFace's buffalo_l weights, which are licensed for non-commercial research only and so could not be published here — they had to be installed by hand and were excluded from the overall "all models are ready" state. If you are upgrading from such a version, press Download AI models once to fetch the new face models, then re-run indexing over photos with people in them: the two model families produce embeddings that are not comparable, so previously detected faces are set aside as unassigned until they are re-detected. Named people are restored as the re-detection proceeds.

4. Model "Missing" Even After Installation

  • Symptom: The plugin reports a model is missing, but it was previously working or you can see the files on disk.

  • Resolution: This can happen if the backend was updated and the model cache path changed, or if the files were only partially downloaded. Delete the affected model's files and download again:

    • macOS/Linux: ~/.cache/lrgenius/models/
    • Windows: %USERPROFILE%\.cache\lrgenius\models\

    The search model is siglip2_* plus tokenizer.json; the species model is bioclip2_*. Delete only the family that is failing, restart the backend, and press Download AI models — the healthy family is skipped.

5. Invalid or Missing API Keys

If you are using cloud providers (Gemini, ChatGPT), authentication failures block all analysis.

  • Symptom: "Unauthorized", 401/403 HTTP errors, or "Gemini API not configured" despite entering a key.
  • Resolution:
    1. Double-check the key in Plug-in Manager → API Keys. Copy-paste directly from the provider dashboard to avoid whitespace.
    2. Ensure the key has not expired and has sufficient billing quota attached.
    3. For Gemini: make sure the Gemini API is enabled in your Google Cloud project.
    4. After saving a new key, restart the backend (the backend reads keys from configuration at startup).

6. Built-In Local Model (llama.cpp / MLX) Not Available

The backend can run models itself, in two independent engines: llamacpp (GGUF) and mlx. Releases ship exactly one per platform — MLX on macOS, llama.cpp on Windows — so you only ever see the section that applies. See Local AI Models for the full guide.

  • Symptom: The Local AI Model section says "This backend does not support MLX".
    • Resolution: Expected on Windows, where the section is llama.cpp instead and offers the same model families as GGUF. On macOS it means a build without the MLX helper — reinstall with the official .pkg.
  • Symptom: MLX is unavailable on an Apple silicon Mac, with a reason naming a missing helper.
    • Resolution: The lrgenius-mlx helper ships next to the server binary in the macOS .pkg. Reinstall the backend with the official installer; if you build from source, the helper needs xcodebuild plus the Metal toolchain (see Server README).
  • Symptom: "This backend build has no local-model support".
    • Resolution: The binary was compiled without the llamacpp feature. Official releases include it — reinstall from the release page, or rebuild with cargo build --release -p lrg-server --features llamacpp.
  • Symptom: A downloaded model does not appear in the model dropdown.
    • Resolution: Check the Installed line in the Plug-in Manager. An interrupted download is discarded rather than offered as a broken model, so simply run the download again.

7. Ollama Not Responding / Not Invoked

  • Symptom: Analysis runs but Ollama shows no activity (ollama ps is empty), or connection errors to localhost:11434.
  • Resolution:
    1. Make sure Ollama is running before starting the task. Start it with ollama serve if needed.
    2. Verify the Ollama Base URL in Plug-in Manager matches where Ollama is listening (default: http://localhost:11434).
    3. Make sure at least one vision-capable model is pulled: ollama pull qwen3-vl:4b-instruct-q4_K_M.
    4. If Ollama runs on a different machine, use its network address instead of localhost.
    5. Check that no firewall or VPN is blocking the connection between the backend and Ollama.

8. LM Studio Not Responding

  • Symptom: Errors connecting to LM Studio, or model list shows no LM Studio models.
  • Resolution:
    1. Open LM Studio and confirm the local server is running (green status in the "Local Server" tab).
    2. Ensure a vision model is loaded (or enable "on-demand model loading").
    3. Verify the LM Studio Base URL in Plug-in Manager (default: http://localhost:1234).
    4. On Apple Silicon, the MLX variants of models perform significantly better than GGUF builds — try the MLX version if performance is poor.

9. Local Model Timeout

Local AI models can take significantly longer than cloud APIs, especially without a dedicated GPU.

  • Symptom: Lightroom displays a timeout error during image analysis.
  • Resolution:
    1. Ensure the model is fully loaded into memory before starting the batch. With Ollama/LM Studio, run a test prompt first; with the built-in engines, the first request of a session loads a multi-gigabyte model and is always the slowest.
    2. Process smaller batches (10–20 photos at a time) to avoid cumulative timeouts.
    3. Switch to a smaller model (4B instead of 12B) if your hardware can't sustain the load.
    4. For the built-in llama.cpp engine: lower Photos in parallel to 1, and check Layers on the GPU — a model that does not fit in VRAM partially runs on the CPU and is far slower.

10. No Metadata Generated

  • Symptom: Analysis completes without errors but no keywords/title/caption appear in Lightroom.
  • Resolution:
    1. In the Analyze & Index dialog, confirm Generate AI metadata is enabled.
    2. If Regenerate all data is disabled, photos that already have metadata in the backend won't be re-generated. Enable regeneration to force a fresh run.
    3. Check that Apply to Lightroom catalog (or equivalent write option) is enabled — without it, metadata is generated on the backend but never written to Lightroom.
    4. After generation, you can always use Retrieve Metadata from Backend to pull generated data back into Lightroom manually.

11. Search Returns No Results

  • Symptom: Advanced Search runs but the results collection is empty or sparse.
  • Resolution:
    1. Make sure photos were indexed with Create search embeddings enabled.
    2. Set the Lightroom collection sort order to Custom Order — without this, best matches are not sorted to the top.
    3. Try a broader or more descriptive query.
    4. Confirm the backend is running and returning a valid response (check Plugin Manager → Status).

12. macOS Filesystem Permission Warning After Update

  • Symptom: Lightroom shows a filesystem permissions warning on startup after installing or updating LrGeniusAI.

  • Resolution: Run Adobe's permission repair script: Adobe: Fix Lightroom user account permissions (macOS)

    This is a known macOS quirk when a third-party plugin installer writes to certain directories. Running Adobe's script resolves it without any data loss.

13. AI Edit Fails Per Photo

AI Edit builds every recipe from your saved training examples and never calls a language model, so its failures are about the style profile, not about models or prompts.

  • Symptom: "Style engine inactive: only N training example(s) available".

  • Resolution: Save more edits via Save Edits as AI Training Examples. Five is the minimum; ten or more gives a usable match. The plugin normally stops before the run and tells you this — seeing it per photo means examples were removed while the run was in progress.

  • Symptom: "Style engine could not produce a result" or "Style engine returned an empty recipe".

  • Resolution: Your training examples carry no usable develop settings for this photo — most often because they were all saved from photos on the other side of the raw/JPEG divide, which keeps their white balance (and little else) from being carried over. Save examples edited from the same kind of file you are trying to edit.

  • Symptom: Low confidence in the review dialog, edits that don't feel like yours.

  • Resolution: The photo did not resemble anything you trained on. Make sure the photos are indexed (Enable smart photo search) so the visual match has an embedding to work with, and train on the kind of material you want edited.

  • Symptom: "HTTP status: 500" with "database not initialized".

  • Resolution: The backend has no catalog database bound yet. Open the Plug-in Manager and let it initialize, then retry.

14. Database Initialization Failed After Update

  • Symptom: "Failed to initialize database at the selected path" error when starting the backend or when Lightroom connects.
  • Resolution:
    1. Ensure the plugin and backend are the same version (see Version Mismatch).
    2. Check that the backend has write access to the configured data directory.
    3. If the path was changed in a previous version, verify the new path in Plug-in Manager → Backend Server.
    4. As a last resort, create a DB backup first (Plug-in Manager → Download DB backup), then let the backend re-initialize with a fresh database.

15. Windows: Restart/Update Endpoint Not Working

  • Symptom: "Check for Updates" or backend restart from within Lightroom fails on Windows.
  • Resolution: This is a known issue on Windows with the /restart endpoint. Restart the backend manually:
    1. Close Lightroom or stop the backend process.
    2. Run lrgenius-server/lrgenius-server.cmd again.

Collecting Logs for Bug Reports

If you need to report a bug on GitHub, include the following:

  1. Plugin log: Plug-in Manager → Copy logs to desktop (or Show logfile)
  2. Backend log: The terminal output of geniusai-server, or the log files in the backend's working directory
  3. Environment: OS version, Lightroom Classic version, LrGeniusAI version (plugin + backend)
  4. Steps to reproduce: What you did before the error occurred

Submit bugs at: https://github.com/LrGenius/LrGeniusAI/issues

Clone this wiki locally