Troubleshooting

Troubleshooting

The hosted site cannot reach my backend

Check the browser first. Safari blocks all mixed content, including requests to localhost, so it can never reach a local backend from an HTTPS page. Use Chrome, Edge, or Firefox 84+.

Use localhost, not 127.0.0.1. Firefox exempts the hostname from mixed-content blocking but not the raw IP.

Is the backend actually up?

curl http://localhost:8000/health

Expect {"status":"ok"}. If that fails, the backend is not running or is on a different port. The executable prints the port it chose; it prefers 8000 and falls back if that is taken.

A CORS error in the console means the backend does not consider your frontend's origin allowed. That is expected if you serve the frontend yourself — set FACE_GALLERY_ALLOWED_ORIGINS. See Configuration.

ModuleNotFoundError: No module named 'pkg_resources'

setuptools is missing. Python 3.12 virtual environments no longer include it, and setuptools 81 removed pkg_resources, which face_recognition_models imports at load time.

pip install "setuptools<81"

requirements.txt pins this. An environment created before the pin was added needs it installed by hand.

Installing dlib takes forever, or runs out of memory

pip install dlib compiles from source. Use the prebuilt wheel instead:

pip install dlib-bin
pip install --no-deps face_recognition face_recognition_models

Wheels exist for Linux x86_64 and aarch64, Windows x64, and Apple Silicon. Intel Macs still need a source build. See Building the Executable.

macOS will not open the download

"Cannot be opened because the developer cannot be verified" is Gatekeeper objecting to an unsigned binary. Right-click and choose Open, or:

xattr -d com.apple.quarantine ./FaceGallery-macos-arm64
chmod +x ./FaceGallery-macos-arm64

On Windows, SmartScreen's "Windows protected your PC" has More info then Run anyway.

A job is stuck on "processing"

The registry of running jobs lives in memory, so restarting the backend orphans anything that was mid-run. It cannot be resumed. Delete the session and start again.

The same person shows up twice

Automatic matching is not perfect. Open Faces in the header, select both cards, and merge them. Nothing is deleted, so you can undo it.

If it happens often, lower the match tolerance in Processing Settings before the next run. Note that settings apply to future runs only.

Two different people were merged into one

Raise the tolerance slightly, or fix it after the fact: ungroup them from the Faces dialog, or use "Edit Faces" on individual photos to correct the assignments.

Upload rejected with 413

The request exceeded a limit: 50 MB per file, 500 MB per request, 10000 images per job, or 1 GB decompressed for a ZIP. Upload in smaller batches or raise the limits — see Configuration. Raising them raises peak memory use, since each file is held in memory while it is validated.

Some photos were skipped

Files that are not decodable images are rejected, even with a valid extension. The processing page lists what was skipped and why. A photo where no face is detected is not an error — it is processed and recorded as having none.

The graph view is sluggish

Expected past roughly 30 images. Open Effects in the sidebar and turn off edge animation and glow first; those cost the most. The app suggests this on its own for larger sets.

Bounding boxes look slightly off on large photos

Detection runs on a copy scaled to 1600 px on the long edge, so recorded boxes land within about 30 px of the full-resolution result on a 12 MP photo. Face crops are unaffected, because they are taken from the original.

Raise DETECTION_MAX_LONG_EDGE in processing.py to trade speed for tighter boxes.