Diagnostics and monitoring
Start with preflight when a film fails. Health endpoints are for monitoring the running web process.
Preflight
The endpoints answer "is the web process up". preflight answers "will a film work on this box":
immich-memories preflight # one row per check: OK, WARNING, ERROR or SKIPPED
immich-memories preflight -v # adds a Details column
In Docker: docker compose exec immich-memories immich-memories preflight.
It checks the Immich connection and API key (and each extra account), the model files and their digests,
the title renderer, hardware encoding, the output folder, the home base, config paths that don't exist on
this machine, configured notification readiness and saved delivery health, the memory the box has,
and configured service endpoints: caption server, text model, render worker, and ACE-Step when
it is set to run on this machine. It does not send a notification. Its Outside call rows name
enabled geocoding and map destinations, not every outside endpoint (Privacy).
A warning names what is missing and the cut still runs
without it, for example Music (ACE-Step) falling back to a bundled track. Any error exits 1, so a
script or a setup step can stop on it. Run it after an install, an upgrade or a config change.
The reader check waits up to llm.preflight_timeout_seconds per HTTP operation (10 seconds by
default). If a connected reader times out while sending its answer, its row says Reader is slow
to answer. Raise that setting for a busy server, then retry. This changes only the preflight
probe; llm.timeout_seconds still controls normal reader requests.
llm:
preflight_timeout_seconds: 30
The environment form is IMMICH_MEMORIES_LLM__PREFLIGHT_TIMEOUT_SECONDS=30. Other preflight
checks keep their own timeouts.
For an explicitly requested local model check:
immich-memories capabilities --verify-local
This executes synthetic reader/vision and configured local audio checks. It does not download
missing models. Use it after installing local runtimes; ordinary capabilities reports the
configuration without this verification work.
Health endpoints
| Endpoint | Returns | Use it for |
|---|---|---|
GET /health/live | 200 while the web process answers, {"status": "alive", "version": …}. Never contacts Immich | liveness probe |
GET /health/ready | 200 with status: ready when configuration and authenticated Immich access work; 503 with status: degraded otherwise | readiness probe, Uptime Kuma, blackbox exporter |
GET /health | always 200: a ready payload is rewritten to ok, a degraded one passes through as degraded | compatibility only, never a probe |
All three are unauthenticated, on purpose: a container runtime has no session. The Immich check is bounded at 5 seconds, and the answer is reused for up to 10 seconds so a busy poller doesn't hammer Immich. With login on, only a logged-in session sees the automation and run detail (it carries person names and paths); a probe gets the status and the version. A degraded status never stops the app: the UI still serves.
Example of /health/ready with login enabled and no authenticated session. Operational details
are present as null:
{
"status": "ready",
"configuration": "configured",
"immich_reachable": true,
"immich": {
"status": "ready",
"reachable": true,
"api_version_policy": "auto",
"resolved_api_version": "v3"
},
"automation": null,
"last_automation_attempt": null,
"last_successful_auto_run": null,
"pending_delivery_count": null,
"oldest_pending_delivery": null,
"notification_health": null,
"last_successful_run": null,
"in_process_scheduler": null,
"disk": null,
"version": "<the running version>"
}
Logging
INFO by default. immich-memories -v generate … logs at DEBUG; --log-level WARNING keeps
warnings and errors. Both are root options, so they go before the subcommand and work for ui too.
In a container, set IMMICH_MEMORIES_LOG_LEVEL=DEBUG. generate --quiet changes terminal presentation. auto run --quiet disables logging entirely during the run and prints one JSON result line; stale-code warnings can still go directly to stderr. The generation child’s captured output remains available in the private attempt log.
Lines look like 2025-12-15 10:30:00,123 [INFO] immich_memories.generate [abc123]: Assembling final video...: the bracketed run id ties one run's lines together (- outside a run).
IMMICH_MEMORIES_LOG_FORMAT=json writes one JSON object per line with the same fields, so
jq 'select(.run_id=="abc123")' works. IMMICH_MEMORIES_LOG_FILE=/path/to/file.log writes the
same lines to a file as well; in Docker, point it at a mounted path.
Log lines go to stderr. Stdout only carries what a command prints, so runs storage --json,
report --json and auto status --json give you one JSON document you can pipe straight into
jq, whatever the log level. docker logs shows both streams.
Model files
immich-memories models fetch
Run it on installation and after an upgrade. Basic fetches the encoder and WordNet; GPU/Full also
fetch detectors and Laya. An enabled owned local reader also fetches its pinned reader/model
projector; custom GGUF paths remain your responsibility. Matching pinned files are reused. --force downloads again;
--detectors fetches detectors even on Basic. --no-detectors skips them, but does not make a
GPU/Full cut work without required models.
Find the run's output
Docker:
docker compose logs -f immich-memories
Kubernetes:
kubectl logs -n immich-memories deploy/immich-memories -c immich-memories -f
Web jobs keep their own output under cache/web-jobs/; daily automation uses
cache/automation-output/. These are on the persistent data volume.
For selection-model costs, inspect the attempt's llm-usage.json; token totals are a lower bound
when a provider does not report usage.
Model usage records
Selection attempts record model calls, cache hits and token counts in llm-usage.json beneath
cache/editorial-runs/. Reader setup explains service behavior.
Caches
Storage and backups covers disk growth and safe cleanup.
Clearing
Clear only disposable caches, while idle.
Moving an install
Move config, keys and the store.
What a second cut asks again
Compatible facts are reused. New inputs or changed producers may need preparation again. Detector versions explain reuse and refresh.
The facts a cut measures
Selection internals describe banked measurements.
The preview cache scales with your library
Video cache mechanics
Downloaded files are checked before reuse; incomplete downloads are not treated as valid hits.