How to Resolve Broken Image Preview Issues in Immich Server

When Immich starts showing blank tiles, grey placeholders, or broken preview icons instead of your carefully backed-up photos, it can feel alarming. The good news is that broken image previews usually do not mean your original photos are gone. In most cases, the issue is related to thumbnails, permissions, background jobs, storage paths, or reverse proxy configuration. With a structured troubleshooting approach, you can usually bring your Immich gallery back to life without risking your library.

Understanding What “Broken Previews” Usually Means

Immich stores and displays your media in more than one form. Your original photos and videos are the source files, while the preview images you see in the web interface and mobile app are usually generated thumbnails or encoded preview files. This separation is important: a broken preview can simply mean Immich cannot find, read, or generate the smaller display version of the file.

Common symptoms include:

• Grey or black tiles in the timeline
• Broken image icons in the web interface
• Photos opening only after a long delay, or not opening at all
• Mobile app showing placeholders while the web app behaves differently
• Videos without thumbnails
• Errors when trying to open a specific asset

If only thumbnails are broken, your originals may still be safe on disk. If both previews and originals fail to open, you may be dealing with a deeper issue involving storage paths, missing files, or database references.

Step 1: Check That All Immich Containers Are Running

Immich depends on several services working together. A typical Docker setup includes the Immich server, PostgreSQL database, Redis, and machine learning service. If one of these is unhealthy or constantly restarting, previews may fail to load or generate.

From the directory containing your docker-compose.yml file, run:

docker compose ps

Look for containers marked as healthy or running. If a container is restarting, stopped, or unhealthy, inspect the logs:

docker compose logs -f immich-server

You can also check all logs at once:

docker compose logs -f

Pay attention to messages mentioning thumbnail generation, permission denied, file not found, database connection, or storage path. These messages often point directly to the cause.

Step 2: Confirm Your Storage Paths and Docker Volumes

One of the most common causes of broken previews is an incorrect volume mount. Immich needs consistent access to the directory where uploaded files and generated thumbnails are stored. If you recently moved your library, edited your Docker Compose file, changed disks, migrated servers, or restored from backup, paths are the first thing to verify.

Check your environment file and Docker Compose configuration. You may see a variable such as:

UPLOAD_LOCATION=/path/to/your/library

Then confirm the same location is mounted into the Immich container. The host path must exist, must contain your Immich library, and must be readable and writable by the container.

For example, if your host storage is located at:

/mnt/photos/immich

but your Compose file points to:

/mnt/photo/immich

that small difference can cause Immich to display broken previews because it is looking in the wrong place. This is especially common after moving from one NAS, Linux server, or external drive to another.

Step 3: Fix File and Folder Permissions

Even when the path is correct, Immich still needs permission to read originals and write generated previews. Permission errors are especially common on Linux hosts, NAS devices, shared folders, and mounted drives.

First, inspect ownership and permissions:

ls -la /path/to/immich/library

If logs show permission denied, the container user may not be able to access the library. The correct fix depends on your deployment, but generally you need to ensure that the Docker process and Immich services can read and write to the upload directory.

A cautious approach is to update ownership only for the Immich library folder, not your entire disk:

sudo chown -R 1000:1000 /path/to/immich/library

Or adjust permissions more generally:

sudo chmod -R u+rwX,g+rwX /path/to/immich/library

Be careful: do not blindly run permission commands on root directories such as /, /mnt, or your entire home folder. Apply changes only to the specific Immich storage location you understand and control.

Step 4: Regenerate Thumbnails from the Admin Panel

If your original files are intact but previews are missing or corrupted, thumbnail regeneration is often the cleanest solution. Immich includes administrative jobs that can rebuild thumbnails and metadata.

In the Immich web interface:

1. Log in as an administrator.
2. Open Administration.
3. Go to Jobs.
4. Find jobs related to thumbnail generation.
5. Run the missing or full thumbnail generation job as appropriate.

For large libraries, this process can take a long time. Thousands of high-resolution photos and videos may require significant CPU, memory, and disk activity. Let the job finish before assuming it failed. You can monitor progress in the Jobs section and check server logs for errors.

Step 5: Update Immich Carefully

Immich is under active development, and updates often include changes to thumbnail handling, media processing, storage behavior, and database migrations. Running mismatched versions of the server, machine learning container, web app, or mobile app can cause strange behavior, including preview problems.

Before updating, make sure you have a backup of:

• Your PostgreSQL database
• Your Immich upload/library directory
• Your .env file
• Your docker-compose.yml file

Then pull the latest images and restart:

docker compose pull
docker compose up -d

After updating, watch logs carefully:

docker compose logs -f immich-server

If database migrations are running, let them complete. Interrupting migrations can create more serious problems than broken previews.

Step 6: Check Reverse Proxy and URL Configuration

If Immich works locally but previews are broken when accessed through a domain name, VPN, or reverse proxy, the problem may not be Immich’s media processing at all. It may be the way requests are routed.

Reverse proxies such as Nginx Proxy Manager, Traefik, Caddy, or Nginx must correctly pass requests to Immich. Broken preview loading can happen if the proxy blocks large files, strips headers, mishandles WebSocket connections, or uses an incorrect upstream address.

Review these items:

• Proxy target: Make sure it points to the correct Immich server port.
• Upload size limits: Increase client body size if uploads or media requests fail.
• Headers: Preserve forwarded host and protocol headers.
• HTTPS: Ensure SSL certificates are valid and not causing mixed-content issues.
• Public URL settings: Confirm any configured external URL matches how users access Immich.

To isolate the problem, try accessing Immich directly on your local network using its container host and port. If previews work locally but fail through the proxy, focus on proxy configuration.

Step 7: Inspect Failed Assets

Sometimes only certain photos or videos show broken previews. This can happen with unusual file formats, partially uploaded files, unsupported codecs, damaged originals, HEIC images, RAW files, or very large videos.

Open one broken item and compare it with a working item. Ask:

• Is the file format different?
• Was it uploaded from a different device?
• Does the original file exist on disk?
• Can another program open the file?
• Do logs show errors for that specific asset ID?

If the original file itself is corrupt, regenerating thumbnails will not help. In that case, restore the original from backup or re-upload the asset.

Step 8: Verify Disk Space and System Resources

Thumbnail generation needs working space. If your disk is full, Immich may fail to create preview files even though uploads appear to succeed. Check available space:

df -h

Also check memory and CPU usage during thumbnail jobs. A small home server, Raspberry Pi, low-power NAS, or heavily loaded virtual machine may struggle with large video previews and high-resolution images.

If resources are limited, run jobs in smaller batches when possible, avoid running major imports during peak usage, and make sure swap or memory allocation is sufficient. Immich can run beautifully on modest hardware, but media processing is still demanding work.

Step 9: Reconcile Database Records with Files

Broken previews can also appear when the database references files that no longer exist. This may happen after manual deletion, incomplete migration, failed disk restore, or accidental changes inside the Immich library directory.

As a rule, avoid manually modifying Immich’s internal storage structure unless you know exactly what you are doing. Immich tracks assets in its database, so deleting or moving files outside Immich can leave orphaned records behind.

If you suspect a mismatch, review Immich’s administration tools and logs before taking drastic action. For serious cases, restore from a known-good backup. If you maintain regular database and file backups, recovery is much simpler.

Prevention: Keep Your Immich Library Healthy

Once your previews are fixed, it is worth making a few habits permanent. Immich is a powerful self-hosted photo system, but like any personal cloud, it benefits from careful maintenance.

• Back up both database and files. One without the other is incomplete.
• Do not move library folders casually. Update Docker paths carefully when migrating.
• Monitor disk space. Media libraries grow faster than expected.
• Update regularly, but read release notes. Avoid jumping many versions without preparation.
• Use stable storage. Flaky USB drives and unstable network mounts can cause mysterious failures.
• Check logs after changes. Logs often reveal small issues before they become big ones.

Final Thoughts

Broken image previews in Immich can look dramatic, but they are usually fixable. Start with the basics: container health, logs, storage paths, permissions, disk space, and thumbnail jobs. Then move outward to reverse proxies, file formats, and database-file consistency.

The most important principle is simple: protect your originals and database before troubleshooting aggressively. Once you know your data is safe, you can regenerate thumbnails, repair configuration mistakes, and restore the smooth photo-browsing experience that makes Immich so useful. In many cases, the “broken image” is not a lost memory at all; it is just a missing preview waiting to be rebuilt.