What Does “Immich Error Loading Image” Mean and How Do You Fix It?

Seeing “Immich error loading image” can be frustrating, especially when your photo library appears intact but individual thumbnails, previews, or full-size images refuse to open. In most cases, the message does not mean your photos are permanently lost. It usually indicates that Immich, your browser, the mobile app, or the server cannot retrieve, decode, or display the requested image at that moment.

TLDR: The “Immich error loading image” message usually means Immich cannot access or render a photo because of a storage path issue, missing file, permissions problem, failed thumbnail generation, network interruption, database mismatch, or unsupported/corrupted media file. Start by checking whether the original file still exists, then verify Docker volumes, storage permissions, server logs, and Immich service health. In many cases, restarting services, regenerating thumbnails, fixing library paths, or correcting file ownership resolves the problem.

What the Error Means

Immich is a self-hosted photo and video management platform. It stores metadata in a database, keeps original media files on disk or mounted storage, and generates thumbnails and previews for fast browsing. When you open an image, several things must work together: the database entry, the file location, filesystem permissions, Immich server services, background jobs, and the client application.

The message “error loading image” is a broad display error. It does not identify one single cause. Instead, it means Immich expected to show an image but could not complete the request. The problem may be on the server side, such as a missing original file, or on the client side, such as a browser cache issue. The important point is to troubleshoot in a structured way rather than assuming the images are gone.

Common Situations Where It Appears

You may see this error in different parts of Immich. The context can help narrow down the cause.

• Grid thumbnails fail to appear: This often points to thumbnail generation, storage access, or background worker problems.
• Thumbnail appears, but full image does not open: The preview exists, but the original file may be missing, inaccessible, corrupted, or unsupported.
• Only some images fail: This usually suggests file-specific problems, such as unsupported formats, damaged files, or missing originals.
• All images fail suddenly: This often indicates a configuration, Docker volume, reverse proxy, storage mount, or service issue.
• Images fail only on mobile or browser: This may involve cache, app version mismatch, network access, or authentication/session problems.

Most Likely Causes

1. The Original File Is Missing or Moved

Immich stores metadata about assets in its database. If a file is deleted, moved, renamed outside Immich, or becomes unavailable because a mounted drive is disconnected, the database may still show the image entry. When Immich tries to load it, the file cannot be found.

This is common after reorganizing storage folders manually, changing Docker volume paths, migrating servers, replacing hard drives, or restoring only the database without restoring the upload directory.

2. Docker Volume or Storage Path Is Incorrect

Many Immich installations run through Docker Compose. If the upload directory or external library path is not mounted correctly, Immich may start normally while still being unable to reach the actual images. A common example is changing a host directory path but not updating the compose file.

Check that the path inside the container points to the same location where the files actually exist. If the host path is wrong or empty, Immich may behave as though the library exists in the database but cannot load the images.

3. File Permission Problems

Immich needs permission to read original images and write generated files such as thumbnails and encoded previews. If files are owned by another user, copied from another system, restored from backup with changed ownership, or stored on a network share with restrictive permissions, Immich may fail to serve them.

Permission errors are especially common on Linux servers, NAS devices, NFS mounts, SMB shares, and external drives. Even if you can see the files from the host machine, the Immich container or service user may not have access.

4. Failed Thumbnail or Preview Generation

Immich relies on background workers to generate thumbnails, previews, metadata, and encoded video assets. If these jobs fail, the interface may not display images correctly. This can happen after an interrupted upload, low memory, corrupt image file, outdated version, or failed machine learning/microservice dependency.

In this case, the original image may still be safe, but the generated display version is missing or broken. Regenerating thumbnails or rerunning jobs can often fix the issue.

5. Corrupted or Unsupported Media Files

Some files cannot be decoded properly. This may happen with corrupted images, incomplete uploads, unusual RAW formats, HEIC/HEIF variations, malformed JPEG files, or files created by specific camera apps. Immich supports many common formats, but compatibility can vary depending on server libraries and versions.

If only one or two images fail while others work normally, download or inspect the original file directly. Try opening it with another image viewer. If other software also struggles, the file itself may be damaged.

6. Reverse Proxy or Network Issues

If Immich is accessed through a reverse proxy such as Nginx, Traefik, Caddy, Cloudflare Tunnel, or another gateway, configuration problems can stop images from loading. Large image requests may time out, headers may be blocked, upload limits may be too low, or WebSocket and API routes may be misconfigured.

This is more likely when images load correctly on the local network but fail remotely, or when thumbnails appear inconsistently over mobile data or external access.

7. Version Mismatch or Incomplete Upgrade

Immich is actively developed. If the server, mobile app, web frontend, and database migrations are not aligned after an update, unexpected display errors can occur. Running containers from mixed versions, skipping migration steps, or using an outdated mobile app may cause failures.

Always read release notes before upgrading, especially for self-hosted services that manage important personal data.

How to Fix “Immich Error Loading Image”

Step 1: Confirm the File Exists

Start with the simplest check. Locate the original image on your server or storage volume. If you know the upload or library path, browse to it from the host system. Confirm that the image is physically present and has a reasonable file size.

If the file is missing, Immich cannot load it. You will need to restore it from backup, reconnect the correct storage device, or correct the library path. If you recently migrated Immich, verify that you restored both the database and the media directories.

Step 2: Check Immich Service Status

Make sure all required Immich containers or services are running. In a Docker Compose installation, this usually includes the server, microservices, database, Redis, and machine learning service depending on your setup.

You can inspect container status with a command such as:

docker compose ps

If a container is restarting, unhealthy, or stopped, review its logs. A stopped background service can prevent thumbnails and previews from being generated.

Step 3: Review the Logs

Logs are one of the most reliable ways to identify the actual cause. Look for messages such as file not found, permission denied, failed to read asset, thumbnail generation failed, or database error.

For Docker Compose, you can check logs with:

docker compose logs -f

To focus on recent errors, watch the logs while trying to open a failing image in the browser. The server response at that exact moment often reveals whether the problem is storage, permissions, transcoding, or network related.

Step 4: Verify Docker Volumes and Mounts

Open your Docker Compose configuration and review the volume mappings carefully. Confirm that the host path exists and contains your images. A small typo, changed drive name, or missing mount can break access to the entire photo library.

For example, if your uploads are supposed to be stored at /mnt/photos/immich, make sure that exact location is mounted into the container and accessible. Also confirm that external libraries point to the correct container path, not just the host path.

Step 5: Fix Ownership and Permissions

If the logs show permission errors, correct file ownership and access rights. The exact command depends on your operating system, user IDs, and deployment method, so do not blindly run ownership changes without understanding your setup.

In general, Immich needs read access to original files and write access to its upload and generated asset directories. On NAS or network shares, also check mount options. Some SMB or NFS mounts may appear readable to your login user but not to Docker containers.

Step 6: Regenerate Thumbnails and Metadata

If the original files exist and permissions are correct, the issue may be with generated thumbnails or previews. Immich provides administrative jobs for tasks such as thumbnail generation, metadata extraction, and library scanning.

From the Immich administration interface, check the jobs page and rerun relevant jobs for missing thumbnails or metadata. This can repair many cases where the database record is valid but the display assets were never created or became inconsistent.

Step 7: Test in Another Browser or Device

Client-side problems are less common than server-side issues, but they do happen. Clear the browser cache, try a private window, disable aggressive extensions, or test another browser. If the problem appears only in the mobile app, update the app and sign in again.

If images load locally but not remotely, focus on your reverse proxy, SSL configuration, DNS, firewall, or tunnel provider. Large images and videos may expose proxy limits that ordinary page loads do not.

Step 8: Check for Corrupted Files

If only specific images fail, download the original file directly from storage and test it with a local image viewer. Also check whether the file size looks plausible. A zero-byte file or unusually small file may indicate an interrupted upload or failed copy.

For RAW or HEIC files, try converting the image to a standard JPEG as a test. If the converted image works, the issue may be format support rather than Immich storage.

Step 9: Update Immich Carefully

If you are running an older version, check whether the issue has already been fixed in a newer release. However, because Immich stores important personal data, update carefully. Back up the database and media files first, read the release notes, and ensure all containers use compatible versions.

After updating, restart the stack and allow background jobs to complete. Some migrations and asset jobs may take time on large libraries.

Preventing the Error in the Future

The best way to avoid this error is to treat Immich as a serious data management system, not just a casual photo viewer. Your photos, database, folders, and configuration all need to remain consistent.

• Back up both the database and media files. A database-only backup is not enough, and a files-only backup may lose metadata and albums.
• Avoid manually moving uploaded files. If you need to migrate storage, follow a planned process and preserve paths where possible.
• Monitor disk space. Full disks can interrupt uploads, thumbnail generation, and database operations.
• Use stable storage mounts. If using a NAS, make sure mounts reconnect reliably after reboot.
• Review logs after upgrades. Catching errors early prevents a small configuration issue from becoming a large library problem.
• Keep client and server versions compatible. Update the web server, containers, and mobile apps in a coordinated way.

When to Restore From Backup

You should consider restoring from backup if original files are genuinely missing, a migration went wrong, or the upload directory was accidentally overwritten. Before restoring, stop Immich services to avoid additional changes, identify the last known good backup, and restore both database and media files from the same time period if possible.

If only generated thumbnails are missing, a full restore is usually unnecessary. Regenerating jobs is safer and less disruptive. Reserve full restoration for cases involving lost originals, database corruption, or major path mistakes.

Final Thoughts

“Immich error loading image” is a symptom, not a final diagnosis. The image may be safe, but Immich cannot currently retrieve or display it. The most effective approach is to verify the original file, check storage paths, inspect permissions, read logs, and then regenerate thumbnails or repair configuration as needed.

For a self-hosted photo library, reliability depends on disciplined maintenance. Keep backups current, document your storage paths, update cautiously, and monitor service health. With a careful troubleshooting process, most Immich image loading errors can be fixed without losing your photos.