Skip to content

Troubleshooting

Jump to bottom
Holden Salomon edited this page Jun 12, 2026 · 11 revisions

Troubleshooting

Container exits immediately

Check logs:

docker compose logs winnow

Common causes:

  • Missing required env var — IMMICH_URL or API_KEY not set
  • Cannot reach Immich — check the URL and that Immich is running; use http:// not https:// unless you have TLS set up

"Immich API key is invalid or expired (401 Unauthorized)"

Your API key has been revoked or expired. Generate a new one in Immich → Account Settings → API Keys and update API_KEY in your .env.

Getting more log detail

Set VERBOSE=true in .env (or pass -e VERBOSE=true) to enable DEBUG-level output on the console. Useful for tracing exactly which images are being fetched, filtered, and selected.

The log file at /app/winnow.log always captures DEBUG regardless of VERBOSE:

docker exec winnow cat /app/winnow.log

"No people found" / nothing processed

  • Make sure Immich has completed face recognition and you have named people in your library
  • YEARS_FILTER defaults to 10 years — increase it if your tagged photos are older
  • MIN_FACE_COUNT skips people with few photos — lower or remove it

Frigate upload fails

  • Confirm FRIGATE_URL is reachable from inside the container: docker exec winnow curl $FRIGATE_URL/api/stats
  • Check Frigate v0.16+ — older versions don't have the face training API
  • Set DRY_RUN=true to verify selection without uploading

Models fail to download

winnow downloads InsightFace and HuggingFace (SigLIP) models on first run.

  • Ensure the container has internet access
  • Confirm the model volume is mounted and writable
  • If behind a proxy, set HTTP_PROXY / HTTPS_PROXY env vars

Running on CPU (no GPU)

Use the :cpu image tag (ghcr.io/sudolulo/winnow:cpu) which omits the CUDA base entirely. Or set FORCE_CPU=true with :latest to disable GPU at runtime.

Everything works on CPU but embedding computation is slower — typically tens of seconds per person instead of under a second on GPU.

If you have a GPU but it's not being used:

  • Confirm the NVIDIA container toolkit is installed: docker run --rm --gpus all nvidia/cuda:13.3.0-base-ubuntu22.04 nvidia-smi
  • Confirm the deploy.resources.reservations.devices block is present in compose.yml
  • Set VERBOSE=true and check the logs — winnow logs which ONNX execution providers are active at startup (should show CUDAExecutionProvider)

Same images uploaded every run

The upload tracker is stored in CACHE_DIR (/app/.if_cache by default). If this volume isn't persisted between runs, the tracker resets and images are re-uploaded.

Make sure /app/.if_cache is mounted to a persistent host path.

Re-uploading a specific person

To clear the upload history for one person and start fresh:

RESET_PERSON=John

Remove this after one run — it clears the history and then processes normally.

Image quality issues

  • Too blurry: Lower BLUR_THRESHOLD (default 100) — e.g. 50 accepts more blur
  • Face too small: Lower MIN_FACE_WIDTH (default 50px)
  • Low confidence detections included: Raise MIN_CONFIDENCE (default 0.7)
  • Rejected images being re-tried: Set RETRY_REJECTED=true for one run

Clone this wiki locally