How to Debug Immich Image Loading Errors in Docker or Self-Hosted Setup

When a self-hosted Immich instance stops loading thumbnails, previews, or full-resolution images, the cause is usually somewhere between the reverse proxy, Docker networking, storage mounts, background jobs, or browser-side caching. A careful administrator can narrow the problem quickly by checking logs, confirming container health, validating file paths, and reviewing Immich’s configuration.

TLDR: Immich image loading errors are most often caused by incorrect upload paths, failed thumbnail jobs, permission problems, broken reverse proxy settings, or unhealthy Docker containers. The fastest debugging path is to check the Immich server, machine learning, Redis, PostgreSQL, and microservices logs, then verify that uploaded files exist where Immich expects them. If thumbnails are missing, rebuilding thumbnails or rerunning jobs often fixes the issue. If images fail only through a domain name, the reverse proxy or external URL configuration is usually the problem.

Understanding the Type of Image Loading Error

Before changing configuration, the administrator should identify which image loading problem is occurring. Immich may show different symptoms depending on the failing component. For example, the web interface may load correctly while thumbnails appear as gray boxes, or albums may open but full-size assets fail with a broken image icon. In other cases, the mobile app may upload images successfully, but the browser cannot display them later.

Common patterns include:

• Blank thumbnails: The asset exists, but thumbnail generation may have failed.
• Broken full-size image previews: The original file may be missing, inaccessible, or blocked by a proxy.
• Images load locally but not remotely: A reverse proxy, SSL, or external URL issue is likely.
• New uploads work but old images do not: A migration, storage path, or permission issue may have affected older files.
• Only videos or HEIC images fail: Transcoding, codec support, or machine learning services may need attention.

Once the pattern is known, debugging becomes much more direct. Immich is composed of multiple services, so the error may not be in the web interface itself. The database may know about an asset, while the file system may not contain it, or a background job may have failed before thumbnails were created.

Checking Docker Container Health

In a Docker or Docker Compose setup, the first step is to confirm that all Immich containers are running and healthy. The administrator can inspect the stack with:

docker compose ps

A typical Immich setup includes services such as the Immich server, Immich machine learning container, PostgreSQL, Redis, and sometimes separate microservices depending on the version and compose file. If any service is restarting repeatedly, stopped, or marked unhealthy, image loading may fail indirectly.

The logs usually reveal the most important clues. The administrator should check:

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

Useful log messages may mention missing files, permission denied errors, failed thumbnail generation, database connection failures, or invalid paths. If the server log complains that an asset cannot be found, the problem is probably related to the upload location or a volume mount. If the machine learning container is failing, search and recognition may be affected, though basic image loading is more often tied to server and storage issues.

Verifying Upload Location and Volume Mounts

Immich stores original photos and generated files in the upload directory configured in Docker Compose. A very common self-hosted problem occurs when the host directory is changed, renamed, moved, or mounted incorrectly. The database still references assets, but the server cannot read the files.

The administrator should review the relevant volume configuration in docker-compose.yml. It may look similar to:

volumes:
  - ${UPLOAD_LOCATION}:/usr/src/app/upload

The UPLOAD_LOCATION value is usually defined in an .env file. If this path points to the wrong host directory, Immich may start normally but fail to display existing images. The administrator should compare the configured path with the actual location of uploaded files on disk.

Inside the container, the upload directory can be inspected with:

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

If the directory is empty when it should contain assets, the volume mount is wrong. If files are visible but cannot be opened, permissions may be the issue. If the files exist on the host but not in the container, Docker is not mounting the expected directory.

Fixing File Permission Problems

Permission errors are another frequent cause of Immich image loading failures. This often happens after files are copied from another machine, restored from backup, moved from one disk to another, or placed on a network share. Immich must be able to read original files and write generated thumbnails, encoded videos, and metadata files.

Docker containers run under specific user and group IDs. If the upload folder is owned by root or by a user that the container cannot access, the application may fail when trying to read or generate images. The server logs may show messages such as permission denied, EACCES, or operation not permitted.

The administrator should inspect permissions on the host:

ls -lah /path/to/immich/upload

If needed, ownership and permissions can be corrected carefully. A common approach is to ensure that the Docker process or configured container user can read and write the directory. The exact command depends on the environment, but it may involve chown or chmod. On network storage, the administrator should also check NFS or SMB mount options, because Docker containers may see different permissions than the host user.

Reviewing Reverse Proxy and External URL Settings

If Immich images load correctly through a local IP address but fail through a public domain, the issue is likely related to the reverse proxy. Nginx Proxy Manager, Traefik, Caddy, Apache, and Cloudflare Tunnel can all work with Immich, but incorrect headers, body size limits, WebSocket handling, or SSL settings may cause broken media loading.

The administrator should confirm that the public URL configured in Immich matches the address used by clients. A mismatch between HTTP and HTTPS, or between local and external hostnames, can cause browsers to block image requests or request the wrong endpoint.

Important reverse proxy checks include:

• SSL termination: The proxy should serve valid HTTPS if clients access Immich over HTTPS.
• Forwarded headers: Headers such as X-Forwarded-Proto and X-Forwarded-Host should be passed correctly.
• Upload size limits: Large media files require generous request body limits.
• Timeouts: Slow storage or large assets may need longer proxy timeouts.
• WebSocket support: Some Immich features rely on real-time communication.

Browser developer tools are useful here. The administrator can open the Network tab, reload Immich, and click a failed image request. A 404 usually suggests a missing route or file. A 401 or 403 suggests authentication or access problems. A 502 or 504 points to the proxy or upstream container. Mixed content warnings mean HTTPS pages are trying to load HTTP assets.

Checking Thumbnail and Preview Generation

If original images are present but thumbnails are missing, Immich’s background jobs may have failed or may not have completed. Immich generates thumbnails and previews after uploads, and these generated files are what users often see in the timeline and album grid.

The administrator should look in the Immich administration interface for jobs related to thumbnail generation, metadata extraction, video transcoding, and library scanning. Failed or stalled jobs can often be retried from the jobs panel. If many assets were imported or restored from backup, the queue may simply need time to finish.

In some cases, the administrator may need to rerun thumbnail generation for affected assets. This is especially relevant after a migration, upgrade, or storage restoration. Before triggering large jobs, the server should have enough CPU, memory, and disk space. Thumbnail regeneration for a large library can consume significant resources and may take hours.

Confirming Database and File System Consistency

Immich stores asset records in PostgreSQL, while the actual image and video files live on disk. Image loading errors can occur when these two sources of truth drift apart. For example, a database backup may be restored without restoring the upload folder, or the upload folder may be restored from a different date than the database.

When the database references files that no longer exist, the web interface may still show assets, but image requests fail. When files exist without database records, Immich will not automatically display them unless they are imported through the correct library workflow.

A careful backup strategy should include both:

• The PostgreSQL database: Contains users, albums, asset records, metadata, and relationships.
• The upload directory: Contains original media and generated assets.

If image errors started after a restore, the administrator should verify that the database and upload directory came from the same backup point. Restoring only one of them often creates broken references.

Investigating Browser and Client Issues

Not every image loading error is server-side. A browser may cache stale requests, block content due to privacy extensions, or fail because service worker data is outdated. If images fail in one browser but work in another, the administrator should test with a private window, clear site data, or disable extensions temporarily.

Mobile clients can also have stale server configuration. If the server URL changed from HTTP to HTTPS, or from an IP address to a domain, the mobile app may need to be updated with the correct endpoint. Logging out and back in can sometimes refresh tokens and asset URLs.

Checking Disk Space and Storage Health

Low disk space can silently break image generation and uploads. Immich may accept database records but fail to write thumbnails or previews if the storage volume is full. The administrator should check available space on the host and inside the container mount:

df -h

Storage errors may also come from failing disks, unavailable network shares, or delayed mounts after reboot. If Immich starts before a remote storage mount is available, Docker may create an empty local directory at the mount path. That can make the application appear to have lost all images. Ensuring that storage mounts are available before Docker starts can prevent this problem.

Reviewing Recent Updates or Migrations

If image loading broke after an Immich upgrade, the administrator should read the release notes for breaking changes, required environment variables, or compose file updates. Immich evolves quickly, and older Docker Compose files may become incompatible with newer versions.

Good upgrade practice includes pulling the latest compose template, comparing environment variables, backing up the database and upload folder, then restarting the stack cleanly:

docker compose pull
docker compose up -d

After an upgrade, logs should be monitored until migrations complete. Interrupting database migrations or downgrading without a proper rollback can create additional problems.

A Practical Debugging Checklist

When the cause is unclear, the administrator can follow this checklist in order:

1. Confirm which images fail: thumbnails, previews, originals, videos, or all media.
2. Run docker compose ps and confirm all services are healthy.
3. Check Immich server logs for missing files, permissions, or failed requests.
4. Verify that UPLOAD_LOCATION points to the correct host folder.
5. Inspect /usr/src/app/upload inside the container.
6. Check file ownership and permissions on the upload directory.
7. Test access by local IP and public domain to isolate proxy issues.
8. Use browser developer tools to inspect failed image requests.
9. Review background jobs and rerun thumbnail generation if needed.
10. Check disk space, network mounts, and recent upgrades.

By moving through these steps methodically, the administrator avoids random changes that may make the problem harder to diagnose.

FAQ

Why does Immich show gray boxes instead of thumbnails?

Gray boxes usually mean that thumbnail or preview generation failed, is still queued, or cannot write to the upload directory. The administrator should check background jobs, server logs, disk space, and file permissions.

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

This usually points to a reverse proxy or external URL problem. The administrator should check HTTPS settings, forwarded headers, proxy timeouts, and browser network errors.

Can missing files be fixed by restarting Docker?

A restart may help if a service is stuck, but it will not restore missing files. If the upload directory is mounted incorrectly or files were deleted, the administrator must fix the mount path or restore the files from backup.

Does Immich store photos in the database?

No. Immich stores metadata and asset records in PostgreSQL, while the actual image and video files are stored on the file system in the upload directory.

Why did images disappear after restoring a backup?

The database and upload directory may have been restored from different points in time, or only one of them was restored. Immich requires both to remain consistent.

Should thumbnails be regenerated after migration?

In many cases, yes. If thumbnails are missing or broken after a migration, rerunning thumbnail generation from the administration jobs panel can resolve the display problem.

What log should be checked first?

The Immich server log is usually the best starting point because it handles asset requests and often reports missing files, permission errors, and failed image responses.