.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Your Immich timeline fills with gray tiles reading "error loading image", and the alarming part is how healthy everything else looks: uploads work, the originals open sometimes, the server says it's fine.
Deep breath first: this error is almost never about your photos. The originals sit untouched on disk; what's failing is the thumbnail pipeline or the path those thumbnails travel to your screen. That distinction shapes the whole diagnosis, which goes from thirty-second fixes to the one structural cause people miss.
Thumbnail problem or delivery problem
Open one failing photo full-screen. If the full image loads while the grid tile stays broken, thumbnails are your problem, continue below. If nothing loads at all, jump to the proxy and disk sections, because the asset itself isn't being served. And do one lap of the trivial checks that solve a surprising share of reports: hard-refresh the browser (Ctrl+F5), try a private window and try another device. A stale service worker or a phone app's cache shows exactly this symptom and clears in one refresh; on mobile, clearing the app's cache from your device settings does the same.
Fix 1: Regenerate thumbnails
Thumbnails are generated by background jobs, and jobs fail quietly: an update interrupted them, the ML container was down that week, a batch errored on odd files. The repair is built in. Administration » Jobs, find Thumbnail generation and run it for missing assets first (fast, targets only the gaps). If tiles stay gray, run it for all assets, which rebuilds everything and takes proportionally longer on big libraries.
Watch the queue while it runs. Counts going down: good, and tiles start filling within minutes as their thumbnails land. Counts frozen with active jobs stuck: the queue itself is wedged, and a container restart un-wedges it more often than any other single action:
docker compose restart immich-server immich-machine-learningFix 2: Check disk space and permissions
A full disk breaks thumbnail generation while uploads sometimes still squeak through, producing precisely this half-working state. On the server:
df -hAnything at or near 100% on the volume holding UPLOAD_LOCATION is your answer. Thumbnails, encoded videos and the database all write to disk continuously, and photo libraries grow toward full disks like it's their job (it is). Clear space or grow the volume, restart the containers, re-run the thumbnail job. If the library has structurally outgrown the machine, that's the moment for a storage VPS rather than another round of deleting.
The adjacent variant: permissions. If UPLOAD_LOCATION or its thumbs folder changed ownership during a migration or restore, the server can read originals it can't write thumbnails next to. docker compose logs immich-server will be shouting EACCES or permission denied if so, and a chown of the library path back to the container's user ends it.
Fix 3: Reverse proxy limits and timeouts
The structural cause behind chronic cases: Immich sits behind Nginx or another proxy, and the proxy's defaults strangle the app. Nginx ships a 1 MB body limit that breaks uploads, and tight timeouts plus missing websocket headers break the live-loading behavior the timeline depends on. The tell is everything working on the LAN address while the domain misbehaves. Immich's reverse proxy docs carry the known-good blocks, with the load-bearing lines for Nginx being:
client_max_body_size 50000M;
proxy_read_timeout 600s;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";Reload the proxy after adding them, then hard-refresh. Cloudflare's proxy in front adds its own upload ceiling on free plans, so Immich domains proxied through Cloudflare hit walls Nginx never sees; graying the cloud (DNS-only) for the Immich hostname is the usual resolution. General proxy patterns live in our Nginx reverse proxy guide if you're building this layer fresh.
Fix 4: Unsupported formats and corrupt files
When the library is fine except specific stubborn files, the files are the story. HEIC/HEIF from newer phones, some RAW formats and unusual video codecs occasionally defeat the thumbnailer, and a corrupt file (interrupted upload, bad SD card history) defeats everything. Check one suspect from the server:
docker compose exec immich-server ffprobe /data/library/USER/path/to/fileParse errors mean the file itself is damaged; re-export or re-upload it. For format gaps, the release notes matter again, thumbnail support widens steadily and "update, then re-run thumbnail generation for missing" has quietly fixed whole categories of these over time; the safe way to do that update is the usual Immich update routine.
Verify thumbnails and prevent repeats
Proof is the timeline scrolling clean, plus Administration » Jobs showing empty error counts. Prevention is unglamorous: keep disk usage under 85% (set a panel alert, future you says thanks), restart containers after any interrupted update and re-run the missing-thumbnails job after big imports as routine hygiene rather than crisis response.
The error reads scary and retreats fast once you know it's a pipeline complaint, not your photos leaving. They never went anywhere.
