In the event that you receive the Immich Error Loading Image message when attempting to view photos in Immich, then the app cannot create the image preview as well nor cannot read it. This is a widespread problem with the Immich usage among users who use it via Docker or even as a NAS storage or self-hosted servers. The original full-resolution photo is usually intact; however, Immich does not make it when loading the thumbnails or preview data.
This manual covers the reasons behind the mistake, how to find your root cause, and the specific step-by-step solutions to the problem:
Immich thumbnails not showing
Immich cannot display images
Immich Docker permissions issues
Image preview fails after moving storage
Microservices are not generating previews
Thumbnails stuck in the queue
At the conclusion of this guide, your Immich installation will be showing photos in their usual way, and you should be able to see thumbnails.
Understanding the “Immich Error Loading Image” Problem
The Understanding of the “Immich Error Loading Image” Problem.
When you open your gallery in Immich, it will attempt to load the thumbnails, but will not load the original full-size files. The lightweight ones are known as thumbnails, and they enhance speed and lessen the use of memory.
When Immich fails to display images, it normally implies:
| Problem Area | Symptoms |
|---|
| Thumbnails missing or corrupted | Gray icons, broken preview boxes |
| Library folder permissions incorrect | Immich server cannot read photos |
| Wrong Docker volume mapping | Immich sees an empty or wrong directory |
| Microservices not running | No new thumbnails generated |
| Migration-related ownership issues | Previews break after moving to another device |
| App or browser caching old thumbnails | Some images load, others don’t |
Key Insight
Most failures are not with the original files.
They are almost always with thumbnail generation.
Step 1 — Update Immich to the Latest Version
Immich is under active development, and older builds often contain unresolved thumbnail or preview bugs.
Update Using Docker Compose
cd /path/to/immich/
docker compose pull
docker compose up -d
Wait a few minutes for all services to restart.
If your issue was due to an old build, thumbnails will begin to load again.
Step 2 — Regenerate Thumbnails (Fix Broken Previews)
This fixes:
- Immich thumbnails not showing
- Broken gallery previews
- Images that only show when clicked
Regenerate Through the Web UI
- Open Immich Web
- Go to Administration
- Select Maintenance
- Click Regenerate Thumbnails
Immich will schedule thumbnail jobs.
Restart Thumbnail Services
docker compose restart immich-microservices immich-machine-learning
If your library is large, processing may take hours — leave it running.
Step 3 — Fix Immich Library Folder Permission Issues (Most Common)
If Immich cannot read your image directory, previews fail even though the files are there.
Apply Correct Ownership (Works on Linux, NAS, Docker)
sudo chown -R 1000:1000 /path/to/your/photos
Fix Directory & File Permissions
sudo find /path/to/your/photos -type d -exec chmod 755 {} \;
sudo find /path/to/your/photos -type f -exec chmod 644 {} \;
| Purpose | Result |
|---|---|
| Corrects ownership | Immich gains access |
| Ensures readable directories | Prevents “Error Loading Image” |
| Ensures readable files | Allows preview and ML processing |
If you migrated photos from another drive, this step is mandatory.
Step 4 — Correct Immich Docker Volume Mapping
Incorrect volume mounts cause Immich to reference a folder that does not contain your actual library.
Correct Example docker-compose.yml
services:
immich-server:
volumes:
- /data/photos:/usr/src/app/upload
Make sure:
/data/photos= Your real photo folder on your host machine/usr/src/app/upload= The path Immich expects inside the container
Important:
All Immich services must use the same mapped folder path:
immich-microservices:
volumes:
- /data/photos:/usr/src/app/upload
immich-machine-learning:
volumes:
- /data/photos:/usr/src/app/upload
If these differ, previews will break.
Also Read: https://techybrain.net/cyanjfuh-mfregfoh/
Step 5 — Verify All Immich Services Are Running
Immich consists of multiple coordinated components:
| Service | Purpose |
|---|---|
| immich-server | UI & API handling |
| immich-microservices | Thumbnail generator & background jobs |
| immich-machine-learning | Face recognition & metadata extraction |
| redis | Job queue management |
| postgres | Database storage |
Check Status
docker compose ps
Restart Everything
docker compose restart
If immich-microservices is not working, no thumbnails will ever generate.
Step 6 — Clear Local Cache (App & Browser)
Sometimes the thumbnails are updated, but your GPU, browser, or app is still using old cached ones.
On Mobile:
- Long press app → App Info → Clear Cache Only
(Do not clear storage)
On Browser:
Press:
CTRL + SHIFT + R
Now reload the gallery — thumbnails should update.
Also Read: https://techybrain.net/thehrwp/
Step 7 — If You Recently Migrated Your Library
Migration = permissions break.
Symptoms:
- Some images load, others fail
- Only recently moved folders break
- Uploading new images works fine
Correct Fix:
Run ownership & permission commands again on the new storage.
If using NAS (Synology, TrueNAS, Unraid):
- Ensure the SMB/NFS share is mounted with the correct UID/GID
- Avoid “root squash” unless configured manually
- Use Linux file sharing format, not Windows ACLs
Step 8 — Large Library? Thumbnail Queue May Be Processing Slowly
If you added tens of thousands of images, Immich processes them in a queue, which can take hours or days depending on your CPU.
Check Job Queue in Web UI
- Go to Admin → Jobs
If thumbnails are queued → leave Immich running.
Also Read: https://techybrain.net/techyhittools-org/
To Speed It Up:
| Hardware | Result |
|---|---|
| More CPU cores | Faster processing |
| SSD instead of HDD | Instant queue improvements |
| Machine-learning GPU acceleration | Boosts face detection |
Summary Troubleshooting Table
| Symptom | Root Cause | Fix |
|---|---|---|
| Images load only when clicked | Missing thumbnails | Regenerate thumbnails |
| No images load at all | Permission issue | Fix folder ownership & chmod |
| Thumbnails stopped generating | Background services paused | Restart immich-microservices |
| New library won’t load previews | Wrong Docker volume mount | Correct docker-compose.yml |
| The new library won’t load previews | UID/GID mismatch | Reassign ownership and restart |
Conclusion
Image loading problems are normally caused by the Immich Error Loading Image and are normally attributed to:
- Missing or corrupted thumbnails
- Incorrect library folder permissions
- Wrong Docker volume mapping
- Stopped or misconfigured background microservices
With the help of this guide, you will be able to update the image previews, regenerate them, fix permissions, verify mounts, and restart services, and as a result, your Immich will be able to run successfully again.
After getting fixed, Immich is fast, smooth, and reliable in long-term self-hosted storage of photos.
FAQ
1. Why is Immich not loading photos?
Because Immich cannot access the thumbnails or the original files. This is usually permission or mount-related.
2. How do I fix thumbnails in Immich?
Regenerate thumbnails from Administration → Maintenance and restart microservices.
3. Do I need to restart Immich after fixing permissions?
Yes. Restarting ensures services re-scan the folder.
4. Does hardware affect thumbnail generation speed?
Yes. More CPU = faster processing. HDD storage makes processing slower.
