Best Troubleshooting Steps for Immich Image Loading Failures

Immich is a powerful self-hosted photo and video backup platform, but like most containerized applications, it depends on several moving parts working together. When images fail to load, the cause may be as simple as a browser cache issue or as complex as a broken storage mount, failed thumbnail generation job, misconfigured reverse proxy, or unhealthy database connection. A careful troubleshooting process helps an administrator identify whether the problem affects thumbnails, full-resolution assets, mobile uploads, the web interface, or the entire Immich stack.

TLDR: Most Immich image loading failures are caused by broken storage paths, missing file permissions, failed containers, thumbnail job errors, or reverse proxy misconfiguration. The administrator should first check container health, logs, storage mounts, and whether the original media files still exist. If thumbnails are missing, the fix often involves rerunning thumbnail generation jobs or checking worker services. If images fail only through a domain name, the reverse proxy, HTTPS, upload limits, or WebSocket settings should be reviewed.

Understanding What Type of Image Failure Is Happening

Before changing configuration files or restarting services, the administrator should determine what exactly is failing. Immich can display several different symptoms, and each one points toward a different cause.

• Thumbnails do not appear: The asset exists, but Immich cannot show preview images in the timeline or album view.
• Full-resolution images fail to open: The thumbnail may be visible, but clicking the asset produces an error or a blank screen.
• Images load locally but not remotely: The issue may involve a reverse proxy, DNS, HTTPS, or firewall configuration.
• Only new uploads fail: The upload process, background workers, or storage permissions may be broken.
• Only old images fail: The original asset files may have been moved, deleted, or made inaccessible.

This first distinction saves time. A missing thumbnail does not always mean the original photo is gone, and a failed full-size image does not always mean Immich itself is unhealthy. Immich stores metadata in the database, media files on disk or mounted storage, and generated previews separately, so each layer must be checked.

Check Whether Immich Containers Are Running Correctly

The first practical step is to verify the health of the Immich containers. In a typical Docker Compose installation, Immich depends on services such as the server, machine learning service, Redis, PostgreSQL, and sometimes background workers, depending on the version and compose configuration.

The administrator can run:

docker compose ps

Every essential service should be listed as running or healthy. If the Immich server, database, or Redis container is restarting repeatedly, image loading can fail because the web interface cannot retrieve asset metadata, thumbnails, or file paths reliably.

The next step is reviewing logs:

docker compose logs immich-server
docker compose logs immich-machine-learning
docker compose logs database
docker compose logs redis

Useful clues include permission denied, file not found, connection refused, database unavailable, thumbnail generation failed, or asset not found. These log messages often reveal whether the problem is storage-related, database-related, or caused by a failed background job.

Verify Storage Paths and Mounted Volumes

Storage problems are among the most common causes of Immich image loading failures. Immich may still show photo records in the interface because metadata remains in PostgreSQL, while the actual image file is missing or inaccessible on disk.

The administrator should confirm that the upload directory or external library path exists on the host system and is mounted correctly into the Immich container. In the Docker Compose file, the volume mapping must point to the correct location. For example, a host path such as:

/mnt/photos/immich:/usr/src/app/upload

must still exist, must be mounted at boot, and must contain the expected files. If the storage device is a NAS, USB drive, NFS share, SMB share, or cloud-mounted folder, it may have disconnected or remounted with different permissions.

The administrator should check the host path directly:

ls -lah /mnt/photos/immich

If the folder is empty or unavailable, Immich cannot serve original images. If the files exist on the host but not inside the container, the Docker volume mapping is likely wrong. The administrator can inspect inside the container:

docker exec -it immich-server sh
ls -lah /usr/src/app/upload

If the files are missing inside the container, the volume mapping should be corrected before attempting database repairs or reinstallations.

Review File and Folder Permissions

Even when files exist, Immich must be able to read them. A file permission issue can cause images to fail silently in the interface or produce access errors in logs. This commonly happens after media files are copied from another system, restored from backup, moved from a NAS, or edited by a different user account.

The administrator should check ownership and permissions on the upload directory. Immich containers usually run under a specific user or internal container user, and the mapped directory must allow read and write access where needed. A simple directory listing can show obvious permission problems:

ls -lah /path/to/immich/upload

If files are owned by root or another restricted account, Immich may not be able to generate thumbnails, read originals, or write encoded previews. The appropriate fix depends on the deployment, but in general, the storage location should allow the Immich service user to read original files and write to upload, thumbs, encoded video, and profile directories.

Important: The administrator should avoid blindly applying overly permissive settings such as chmod 777 to an entire media library unless it is a temporary diagnostic step in a controlled environment. It is better to correct ownership and group permissions deliberately.

Confirm That Thumbnails and Preview Jobs Are Working

If the Immich timeline shows gray boxes, broken image icons, or missing previews while original photos still open, the problem usually involves thumbnail generation. Immich generates thumbnails and preview assets in the background. When this process fails, the application may still know that the photo exists, but it cannot display a lightweight preview.

The administrator should open the Immich administration area and inspect the Jobs section. Thumbnail generation, metadata extraction, video transcoding, and library scanning jobs should not be stuck indefinitely. If thumbnail jobs failed after an update, storage change, or crash, rerunning the relevant jobs can restore image previews.

Common job-related remedies include:

• Restarting the Immich server and related worker services.
• Rerunning thumbnail generation from the admin interface.
• Checking whether the thumbnail storage directory is writable.
• Reviewing logs for image processing errors.
• Ensuring enough CPU, memory, and disk space are available.

Thumbnail processing can be resource-intensive on large libraries. If the server is low on RAM or disk space, generation may fail repeatedly. A system with thousands of images may take considerable time to rebuild previews, so the administrator should monitor logs and job progress before assuming that the process is stuck.

Check Disk Space and Inode Availability

Immich may fail to load or generate images if the server has run out of disk space. This may affect uploads, thumbnail generation, database writes, or temporary processing files. The administrator should check available storage:

df -h

On Linux systems, inode exhaustion can also cause failures even when disk space appears available:

df -i

If either disk space or inodes are exhausted, Immich may behave unpredictably. Old Docker images, logs, temporary files, and unused backups may need to be removed. However, media directories and database volumes should never be deleted without a verified backup.

Inspect Reverse Proxy and Domain Configuration

If images load correctly when accessing Immich through a local IP address but fail through a public domain, the reverse proxy is a strong suspect. Nginx Proxy Manager, Traefik, Caddy, Cloudflare Tunnel, Apache, and other proxy layers can all affect image delivery.

The administrator should check several proxy-related items:

• Maximum upload and response body sizes: Large images and videos may fail if proxy limits are too low.
• Timeout settings: Slow connections or large files may need longer read and send timeouts.
• HTTPS configuration: Mixed content or invalid certificates may block resources in the browser.
• Forwarded headers: Immich should receive correct protocol and host information.
• WebSocket support: Some Immich features depend on proper real-time communication.
• Cloudflare limits: Proxy upload limits and caching behavior may interfere with large assets.

Browser developer tools are helpful in this scenario. The administrator can open the Network tab and reload the Immich page. Failed image requests may show status codes such as 401, 403, 404, 413, 502, or 504. Each status code narrows the cause. For example, 413 Payload Too Large points to a proxy size limit, while 502 Bad Gateway suggests that the proxy cannot reach the Immich server.

Clear Browser Cache and Test Another Client

Sometimes the server is functioning correctly, but the client has cached old application assets or stale authentication information. This is especially common after an Immich update. The administrator should test image loading in an incognito window, another browser, or another device.

Useful client-side checks include:

• Clearing browser cache and site data for the Immich domain.
• Logging out and logging back in.
• Testing the mobile app and web interface separately.
• Disabling browser extensions that may block media requests.
• Checking whether the issue happens only on Wi-Fi, VPN, or mobile data.

If images work in one browser but not another, the issue is probably client-side. If images fail everywhere, the administrator should continue investigating server-side components.

Verify Database and Asset Metadata Consistency

Immich stores asset information in PostgreSQL. If the database is unavailable, corrupted, or out of sync with the file system, images may not load as expected. For example, after a failed restore, the database might reference files that are no longer present in the upload directory.

The administrator should confirm that the PostgreSQL container is healthy and that Immich can connect to it. Database logs may reveal authentication failures, storage problems, or migration errors. After updates, migrations must complete successfully; otherwise, the application may display assets incorrectly or fail to retrieve them.

For external libraries, the administrator should also verify that library scanning has completed. If files were moved or renamed outside Immich, rescanning may be required. However, if files managed by Immich were manually moved inside the upload directory, metadata references may break. Immich-managed files should not be rearranged manually unless the administrator fully understands the storage structure and has a backup.

Review Recent Updates and Version Compatibility

Image loading failures often appear after an update, especially when the Docker Compose file, environment variables, or required services changed. Immich evolves quickly, so the administrator should compare the currently deployed compose file with the official version for the installed release.

After updating, the administrator should make sure that all containers use compatible image versions. Running an updated server with an outdated machine learning service, Redis, or database configuration may produce unexpected behavior. A clean pull and restart can help:

docker compose pull
docker compose down
docker compose up -d

Before any major version upgrade, a complete backup of the database and media storage should be created. If images stop loading immediately after an upgrade, logs and release notes should be checked for breaking changes, renamed environment variables, or modified volume requirements.

Confirm Network and Firewall Access

Network issues can also prevent images from loading, especially when Immich is split across multiple hosts or accessed remotely. A firewall may allow the web interface but interrupt specific media requests, proxy traffic, or internal container communication.

The administrator should verify that Docker networks are intact and that the reverse proxy can reach the Immich server container. If a NAS or external storage system is involved, the Immich host must maintain stable access to that storage. Temporary network drops can cause mounted libraries to disappear, leading to missing images until the mount is restored and services are restarted.

Use a Safe Troubleshooting Order

A structured troubleshooting order prevents accidental data loss. The recommended sequence is:

1. Identify the symptom: Determine whether thumbnails, originals, uploads, or remote access are failing.
2. Check container health: Confirm that all Immich services are running.
3. Read logs: Look for file, database, permission, proxy, or processing errors.
4. Verify storage: Ensure media files exist on the host and inside the container.
5. Check permissions: Confirm that Immich can read and write required directories.
6. Inspect jobs: Rerun thumbnail generation or metadata extraction if needed.
7. Test direct access: Compare local IP access with domain-based access.
8. Review proxy settings: Fix limits, headers, HTTPS, and timeouts.
9. Check updates: Confirm version compatibility and completed migrations.
10. Restore only if necessary: Use verified backups if files or database records are truly lost.

This approach helps the administrator solve the most common Immich image loading failures without making risky changes. In many cases, the solution is not a reinstall but a corrected mount, repaired permission issue, restarted worker, or proxy adjustment.

Frequently Asked Questions

Why does Immich show photo records but not load the actual images?

Immich may still have asset metadata in PostgreSQL while the original files are missing, moved, unmounted, or unreadable. The administrator should verify that the upload directory or external library path exists both on the host and inside the Immich container.

Why are thumbnails missing while full images still open?

This usually indicates a thumbnail generation problem. The administrator should check the Jobs section, confirm that the thumbnail directory is writable, review server logs, and rerun thumbnail generation if necessary.

Why do images load locally but not through the public domain?

The reverse proxy is likely misconfigured. Common causes include low body size limits, short timeouts, missing forwarded headers, broken HTTPS settings, WebSocket issues, or Cloudflare-related restrictions.

Can clearing the browser cache fix Immich image loading problems?

Yes, especially after an update. Cached application files or stale authentication data can cause broken image requests. Testing in a private window or another browser can quickly confirm whether the issue is client-side.

Should Immich be reinstalled if images fail to load?

Reinstallation is rarely the best first step. The administrator should first check logs, storage mounts, permissions, container health, proxy settings, and thumbnail jobs. Reinstalling without understanding the cause may make recovery more difficult.

What should be backed up before major troubleshooting?

The PostgreSQL database and the full Immich media storage directory should be backed up. A valid backup is essential before migrations, permission changes, storage moves, or restoration attempts.

Why do new uploads fail to display after they complete?

The upload may succeed, but background processing may fail afterward. The administrator should check thumbnail generation, metadata extraction jobs, available disk space, and whether Immich has write permission to its upload and thumbnail directories.