Immich Error Loading Image

First check: can you download the original?

When Immich shows “Error loading image,” open the affected asset in the web app and try downloading its original. A photo still visible on your phone may be a local copy; verify the server download from another device if necessary.

1. If the original loads but the thumbnail or preview fails, check thumbnail jobs and generated files.
2. If the original also fails, inspect the failed request first. When the matching server error identifies a file problem, check the file path, mount and permissions before retrying processing.

Thumbnail regeneration cannot recover a missing original. If the original is confirmed missing, stop before regenerating and use the backup and restore guide to check the available recovery set. Do not delete database records, clear Trash or reset the stack to hide the error. System Integrity ↗

Choose the matching symptom

Record the asset's filename/ID, approximate request time, server and mobile versions, deployment method and whether the failure affects one or many items. Avoid posting personal photos, full environment files or private share URLs in a public issue.

Inspect the failed image request

A failed download does not by itself mean a file is missing. A session, access rule or network failure can prevent the request from reaching the image. Use the optional request result in the guide above to choose a narrower next check.

1. On a desktop browser, open Developer Tools → Network before reproducing one affected image or original download. Keep the panel open during the request.
2. Find the request made at that time. Check All or Fetch/XHR as well as images; do not select an unrelated upload, page or analytics request.
3. Read its status, content type and response locally. Note the time and whether this was an original, preview or tile. A 2xx response can still contain unexpected content; inspect it before calling the image healthy.
4. Compare the same asset and client over an already available trusted local route and public hostname, if applicable. Match the request time to Immich and proxy logs. Do not open a new public port for this comparison.

For 401, recheck sign-in; for 403, check the account and any proxy access rules. For 404, compare the requested route and corresponding logs before concluding the original was deleted. For 429, pause retries and respect Retry-After if supplied. For 5xx, inspect service state and the matching server/proxy error. If no HTTP response arrives, investigate the browser's connection error first. These are next checks based on HTTP semantics, not confirmed Immich diagnoses. HTTP status reference ↗, 429 response ↗

Keep cookies, Authorization headers, query tokens, private share URLs and photos out of public reports. Do not post an unreviewed HAR export or copied cURL command: either can contain credentials. Share only a redacted path, status, time and relevant error. Chrome Network documentation ↗

Request-routing guidance checked October 14, 2026 against the HTTP references and Immich reverse-proxy documentation ↗. This does not reverify the historical cases elsewhere in this article.

Inspect server logs and integrity findings

For the official Docker Compose stack, run these read-only commands on its host in the active Compose directory:

docker compose ps -a
docker compose logs --tail=100

The first shows running, stopped and restarting services; the second shows recent service messages. Reproduce the failure and inspect the relevant output. A service that repeatedly exits needs startup diagnosis before an image-processing retry. The command references define their behavior: Docker ps ↗, Docker logs ↗.

In Administration → Maintenance, review the integrity report. Missing means a recorded file is absent at its expected location; untracked means a disk file is not recorded; checksum mismatch means content differs from what Immich expects. Run a full check to examine more than existing findings. Refresh rechecks only items already reported. These categories need different responses. Integrity reports ↗

Container Manager users can inspect the corresponding container's logs in DSM. A native LXC or packaged TrueNAS/Unraid app may expose different log controls; use its actual service manager rather than assuming the Compose directory exists.

Error loading image after upload

An uploaded asset triggers background jobs, including metadata extraction and thumbnail generation. Upload completion and a usable preview are separate checks. Jobs and Workers ↗

1. Try downloading the new asset's original from the server. If that fails, follow the file and storage checks below; a local phone copy does not prove the server has the original.
2. If the original downloads, inspect thumbnail generation in Administration → Job Queues. Allow active jobs that are making progress to finish. If a job fails or processing stops, inspect its status and the corresponding server logs.
3. Once processing completes, reopen the same tile and preview. If either still fails, use the thumbnail checks below; if only one format fails, check the format and decoder error.

A TrueNAS community report ↗ describes a new import whose errors decreased as processing progressed. It is a first-person case, not evidence that every error resolves by waiting.

Fix thumbnail and preview errors

Symptom: an original opens/downloads, but its thumbnail or large preview fails.

Regenerate missing thumbnails after checking the cause

1. Open Administration → Job Queues and check thumbnail generation for real progress or failed jobs. During an initial import, allow active processing to complete before declaring the whole library broken.
2. Inspect the error for the affected asset. If it identifies a missing or inaccessible generated path, correct the thumbs mount or access first. Do not regenerate repeatedly against an unchanged bad mount.
3. With the original readable and the generated-media directory accessible, retry thumbnail generation for the affected asset where the UI offers it, or run the documented missing-thumbnail job. Watch that asset's server log while it runs.
4. Reopen the same asset and confirm the tile and preview now load. Check that the original still downloads and that the repeated error is gone.

Generated thumbnails and encoded video can be rebuilt from valid originals. Missing jobs are explicitly recommended by the integrity documentation ↗; Jobs and Workers ↗ explains the processing queues.

Historical Discussion #10570 ↗ contains thumbnail-refresh observations without a current universal fix.

Check original files, storage paths and permissions

Symptom: the original download fails, with ENOENT, an access error or a missing-file report.

Read the full path in the error. Determine whether it is an original under upload/library, a derived file under thumbs, or an external mount. Check that exact path from inside the container, not only in the host's file browser. The official external-library diagnostic opens a shell and lists the target:

docker exec -it immich_server bash
ls /mnt/photos

Run the first command on the Docker host; run the second in the container shell. Replace /mnt/photos with the actual container directory reported by your deployment and replace the container name if customized. Listing should reveal the expected files. “No such file” directs you toward path/mount availability; “Permission denied” directs you toward traversal/read access. A root shell listing alone does not prove a custom non-root worker can read the same file. Official path check ↗

For managed uploads, compare the container destination and host storage mapping with the Docker Compose setup guide. Keep your existing media paths while diagnosing access.

If the disk/NAS is mounted somewhere else or did not mount before startup, restore the intended mapping and re-test that original. If the file truly no longer exists in any expected location, locate an intact copy in backup or on the original device and follow the backup recovery guide. Verify the recovered file by downloading it from the server and refreshing the integrity finding.

Historical case: Issue #26720 ↗ reports v2.5.6 on a Debian/Raspberry system using Podman and external storage. Some originals were missing even though assets remained in the database. A maintainer later described a merged write-synchronization change and explicitly said existing missing files would not be repaired automatically. The issue does not establish the first release containing the change, so this guide does not invent a fixed-version number. Absence of an asset_file row alone was not proof of corruption in that discussion.

If only external-library images fail

Symptom: managed uploads work, while files from an existing collection fail or scans return nothing.

Check the additional volume mount, library import path, read access, exclusions and the NAS's availability. The UI path must equal the container-side destination; host access through File Station or the Proxmox console is insufficient. Dedicated worker containers, if configured, need the same path. The standard current stack does not require creating an old standalone microservices container. External Libraries ↗

If a NAS disappears, restore the mount before scanning again or cleaning Trash. Historical Discussion #30820 ↗ describes a v3.1.0 remote-mount outage followed by many offline/trashed external assets. The maintainer recommends restoring visibility and rescanning, while the reporter says recovery remained incomplete. That disagreement remains unresolved; do not use the thread's suggested SQL as an endorsed repair.

Verify a previously failing original opens after the same path is restored. If it does not, preserve the backup and exact scan/log evidence, then follow the detailed external-library guide.

Errors after an update or storage move

Inconsistent Media Location concerns container-side paths. Compare IMMICH_MEDIA_LOCATION, the upload volume's destination and the existing database path model. The official Errors page specifically warns against moving host files merely because this error appears. Its automatic path-transition behavior depends on having started the relevant historical versions successfully. Documented media-location error ↗

A missing .immich marker can mean the mount disappeared, permissions changed or a backup omitted a folder. These markers are safeguards. Confirm the actual storage and restored folders before considering the narrowly documented marker-recreation cases; do not globally disable mount checks. Folder checks ↗

A v2.5.x update report ↗ ultimately identified incorrect .env/NFS mounting. The timing after an update did not prove a version regression. Compare configuration and service errors first, then consult the version-specific update path.

Images work locally but fail through the reverse proxy

Symptom: the same original works through the local server URL but fails through the public hostname.

Test the same asset with the same client through each route. Inspect the failed browser request's status and the proxy log at that time. This comparison isolates the request path; it does not establish a proxy bug on its own. If both routes fail with the same filesystem error, return to storage diagnosis.

Immich's reverse-proxy documentation ↗ requires hosting at the root of a domain rather than a subpath such as /immich, and describes required forwarding headers and request limits/timeouts. Compare your proxy's configuration with its corresponding example. An upload body-size limit concerns uploads; do not assume increasing it fixes every failed image GET.

Use the reverse-proxy setup guide for the configuration checks, then retest the same original and preview through the public hostname.

Verify both local and proxied access to the original and preview after a change. For mobile-only failures, check the phone's actual server URL, network and major-version compatibility as well.

If one file format fails or checksums differ

If only one format or asset fails, compare a known-good JPEG and the failing original, check the supported media formats ↗ and capture the exact decoder/thumbnail error. Do not rename an extension to make unsupported content appear supported. Keep the original and use the error plus exact version when reporting; no universal conversion or decoder workaround is confirmed here.

For checksum mismatch, determine whether the internal original was manually edited or whether storage corruption is plausible. The official integrity guide describes deleting an intentionally modified asset through Immich and uploading it as a new asset, but that changes identity and associations.

Verification and escalation

A branch is resolved when the same previously failing asset opens as an original and preview, relevant jobs finish, and the corresponding storage/log error no longer recurs. Sample more than one affected group before calling a large library repaired. New uploads alone do not test historical data.

If this does not work, report the exact version/platform, one failing asset's redacted path, original-versus-preview result, local-versus-proxy result, job status, and the earliest relevant log error. Link the closest issue only if its environment matches. Do not label a closed issue as fixed without a supporting resolution, or expose private media as a public reproduction.

Advanced cases and FAQ

Multi-instance deployments

Issue #23574 ↗ concerns Ubuntu/Docker v2.2.1 with two instances. Its later comments identify an omitted instance-specific Redis hostname, allowing the wrong instance to process jobs. Verify each instance's queue/cache configuration as well as its database and mounts. The author confirmed the configuration omission; the record is not a complete full-library recovery test. Confirmation comment ↗

Why can the phone show a photo that the web cannot load?

The phone may still display its local copy. That was part of the confusion in #26720 ↗. Verify a server-side original download from another device instead of relying on a phone thumbnail.

Why are there more thumbnail jobs than photos?

The official FAQ describes three thumbnail jobs per asset—blurred representation, preview and thumbnail—plus additional face thumbnails. A larger job count alone does not establish duplicate uploads or a stuck queue. Official FAQ ↗

Sources

• System Integrity ↗ — Official Immich diagnostics and recovery boundaries.
• Jobs and Workers ↗ — Official Immich processing model.
• External Libraries ↗ — Official Immich container-path checks.
• Errors ↗ — Official Immich media-location/version behavior.
• Reverse Proxy ↗ — Official Immich proxy requirements.
• Supported Media Formats ↗ — Official Immich image/video compatibility.
• FAQ ↗ — Official Immich thumbnail job counts.
• Docker ps ↗ — Official Docker reference.
• Docker logs ↗ — Official Docker reference.
• Missing uploaded originals, #26720 ↗ — GitHub issue; historical v2.5.6 record.
• Multiple instances, #23574 ↗ — GitHub issue; historical v2.2.1 queue-isolation case.
• Thumbnail refresh, #10570 ↗ — GitHub discussion; historical user observations.
• External mount outage, #30820 ↗ — GitHub discussion; v3.1.0, unresolved recovery discrepancy.
• Initial TrueNAS processing ↗ — Reddit; user-reported progress.
• Images after v2.5 update ↗ — Reddit; user-reported NFS/configuration correction.