Immich is one of the most popular self-hosted alternatives to cloud photo libraries, giving you control over your memories while offering features such as automatic mobile backup, timeline browsing, albums, facial recognition, and machine learning search. But when photos suddenly stop loading, thumbnails disappear, or the web app spins endlessly, the experience can quickly shift from empowering to stressful. The good news is that most Immich loading problems are caused by a small set of predictable issues, and many can be fixed in minutes if you know where to look.
TLDR: Immich photos usually fail to load because of storage path problems, broken reverse proxy settings, missing files, database mismatches, failed background jobs, or resource limits. Start by checking container health, disk space, logs, upload directories, and whether thumbnails or encoded videos are being generated. If the original files are still intact, access can often be restored by restarting services, fixing permissions, repairing configuration, and rerunning Immich jobs.
What “Photos Fail to Load” Usually Means
Before fixing the issue, it helps to identify exactly what is broken. In Immich, “not loading” can mean several different things. The photo grid may stay blank, thumbnails may show as gray boxes, individual assets may open to a black screen, videos may refuse to play, or uploads may appear in the app but fail when selected. Each symptom points to a different part of the system.
Immich is not just a web gallery. It is a group of services working together: the server, web interface, database, Redis, machine learning service, background workers, storage volume, and sometimes a reverse proxy such as Nginx, Traefik, Caddy, or Cloudflare Tunnel. When one piece falls out of sync, photos may seem to vanish even though the original files are still safely stored on disk.
The most important rule is simple: do not start deleting volumes, rebuilding databases, or moving folders until you confirm where your original media files are located. In many cases, the app cannot display photos, but the files themselves are still present.
Common Reasons Immich Photos Stop Loading
1. The Storage Path Is Wrong or Unmounted
The most common cause is a storage path problem. Immich stores uploaded files in a location mounted into the Docker container, often through an environment variable such as UPLOAD_LOCATION. If that folder is renamed, moved, disconnected, or mounted incorrectly after a reboot, Immich may still show photo records from the database but fail to retrieve the actual files.
- Symptoms: assets appear in the timeline, but thumbnails or full images do not load.
- Likely cause: the database knows the photo exists, but the file path no longer points to a real file.
- Quick check: look inside the upload directory on the host and confirm that library folders and asset files are present.
This often happens after changing Docker Compose files, moving from local storage to a NAS, updating mount points, or rebooting a system before a network share is available.
2. File Permissions Prevent Immich from Reading Media
Even if the files are in the correct folder, Immich still needs permission to read them. Permission problems are especially common when media is stored on external drives, SMB shares, NFS mounts, or directories copied from another machine.
If the containers run as a specific user or group, but the upload directory is owned by another account, the server may fail to generate thumbnails or serve original files. This can look like a broken Immich installation when it is really a simple ownership issue.
Check whether the container user can read and write to the upload location. Fixing ownership or permissions may immediately restore access, although thumbnails may still need time to regenerate.
3. Thumbnail or Preview Generation Failed
Immich does not always show full-size photos directly in the timeline. It relies on generated thumbnails and preview images to make browsing fast. If background jobs stop running, the original photos may be safe, but the interface may appear incomplete or sluggish.
This can happen after an interrupted upgrade, a crashed worker, insufficient memory, or a failed job queue. In that case, opening a single original photo might work, while the grid view remains broken or partially empty.
- Check the Jobs page in the Immich admin interface if available.
- Look for failed thumbnail, metadata, or video transcode jobs.
- Restart the worker containers and re-run missing jobs if needed.
4. Reverse Proxy or URL Configuration Is Incorrect
If you access Immich through a domain name, reverse proxy, VPN, or tunnel, the problem may not be Immich itself. Photos can fail to load when large file requests, WebSocket connections, headers, or upload limits are blocked by the proxy layer.
For example, the Immich web interface might load normally, but individual image URLs return 404, 502, 413, or timeout errors. Videos are especially sensitive because they may require range requests to stream properly.
Pay close attention to:
- Maximum body size for uploads and downloads.
- Proxy timeout settings for slow connections or large files.
- WebSocket support if live updates or background status indicators fail.
- Correct external URL in environment settings and mobile app configuration.
A quick test is to access Immich directly by local IP and port, bypassing the proxy. If photos load locally but not through the domain, your proxy configuration is the likely culprit.
5. Docker Containers Are Unhealthy or Out of Sync
Immich depends on multiple containers. If PostgreSQL, Redis, the Immich server, or worker containers are down or unhealthy, the app may partially load but fail when retrieving assets. An incomplete startup after a reboot is a classic cause, especially on small home servers where storage and database services may start slowly.
Run a container status check and look for repeated restarts, unhealthy states, or services that exited unexpectedly. Then inspect logs for errors related to missing files, failed queries, permission denied messages, or connection failures.
Restarting the full stack can help, but logs are more valuable than guessing. If a service immediately crashes again, the logs usually say why.
Fast Recovery Checklist
When Immich photos fail to load, follow a calm sequence. The goal is to restore access without making the situation worse.
- Confirm the original files exist. Browse the upload location on the host machine and verify that media files are still there.
- Check available disk space. A full disk can break uploads, thumbnails, database writes, and background jobs.
- Review container status. Make sure Immich, PostgreSQL, Redis, machine learning, and workers are running.
- Read the logs. Search for errors such as permission denied, file not found, connection refused, or no space left on device.
- Test local access. Open Immich using the local server address to rule out reverse proxy problems.
- Check permissions. Ensure the container can read and write the upload directory.
- Rerun jobs. Regenerate thumbnails, metadata, and video previews if the files exist but previews are missing.
Disk Space: The Silent Photo Killer
Running out of disk space is one of the easiest problems to miss. Immich may continue to show parts of the interface while silently failing to create thumbnails, write database updates, or complete uploads. A nearly full drive can also corrupt temporary operations, leaving some assets in an awkward half-processed state.
Check both the media storage drive and the drive where Docker volumes live. If your database is on a small system disk while photos are on a large external disk, the database volume can fill up even when the photo library drive has terabytes free.
After freeing space, restart Immich and rerun failed jobs. If uploads failed during the full-disk event, you may need to re-upload those specific files.
Database and File Mismatch Problems
Immich tracks assets in PostgreSQL. The database stores information about each photo, while the media files live in the upload directory. If files are manually deleted, moved, renamed, or restored from an old backup without the matching database state, Immich can point to files that no longer exist.
This mismatch is one reason manual file management inside the Immich upload directory should be avoided. Treat that folder as application-managed storage unless you fully understand the consequences. If you want to import an existing library, use supported external library features or documented import methods rather than dragging files into internal directories.
If a mismatch already happened, your recovery approach depends on what is missing:
- Database exists, files missing: restore the upload directory from backup if possible.
- Files exist, database missing: restore the database backup that matches the files, or re-import media.
- Both exist but paths changed: fix mount paths so Immich sees files where it expects them.
Mobile App Sync Issues
Sometimes the issue appears to be server-side, but only the mobile app is affected. If Immich works in a desktop browser but not on your phone, check the app’s server URL, authentication state, VPN connection, and certificate trust. A changed domain, expired HTTPS certificate, or switched reverse proxy can prevent the app from loading thumbnails even while the web version works.
Logging out and back in can refresh tokens, but avoid clearing app data until you understand whether there are pending local uploads. If your phone has unsynced photos, clearing the app may remove backup state and make troubleshooting more confusing.
When an Update Breaks Photo Loading
Immich develops quickly, and updates can include database migrations, configuration changes, or revised container definitions. If photos fail immediately after an upgrade, compare your Docker Compose file and environment variables with the current official example. A deprecated variable, missing service, or version mismatch can produce strange loading behavior.
Do not upgrade only one container manually while leaving others behind. Immich components are designed to work together at compatible versions. Pull the correct images, restart the complete stack, and watch migration logs carefully.
If the database migration fails, stop and investigate before repeatedly restarting. A failed migration is not always disastrous, but careless recovery attempts can make it harder to roll back.
How to Restore Access Quickly Without Panic
The fastest path to recovery is usually not a dramatic rebuild. It is a methodical reset of the parts most likely to fail. First, verify storage. Second, verify services. Third, verify networking. Fourth, regenerate derived assets such as thumbnails. This order prevents you from wasting time on cosmetic fixes while the real issue sits in a missing mount or full disk.
A practical recovery flow looks like this:
- Restart the stack after confirming your storage mounts are active.
- Open logs immediately and watch what happens as Immich starts.
- Browse to a known photo and check whether the original file path exists.
- Bypass your proxy to isolate local Immich behavior from internet-facing access.
- Run missing jobs if originals load but thumbnails or previews do not.
- Restore from backup only after identifying whether the database, files, or both are affected.
Prevention: Make Immich More Resilient
Once access is restored, spend a little time preventing the same problem from returning. Self-hosting gives you freedom, but it also makes backups and monitoring your responsibility.
Use a backup strategy that includes both the PostgreSQL database and the upload directory. Backing up only the photos is not enough to preserve albums, metadata, people, favorites, and timeline state. Backing up only the database is also not enough because the actual photo files are separate.
It is also smart to monitor disk space, container health, and backup success. A simple alert for low storage can prevent many Immich failures before they begin. If you use a NAS or remote mount, make sure Docker does not start Immich before the storage is available after reboot.
Final Thoughts
When Immich photos fail to load, it can feel as if your entire photo archive is at risk. In most cases, however, the problem is not lost memories but a broken connection between the web interface, database, background jobs, and storage. By checking files first, then permissions, containers, logs, proxy settings, and jobs, you can usually restore access quickly and safely.
Immich is powerful because it brings cloud-like photo management into your own hands. The tradeoff is that you become the operator of the system behind the gallery. With good backups, careful updates, and a clear troubleshooting routine, photo loading failures become less of a crisis and more of a solvable maintenance task.