Immich has become a popular self-hosted photo and video management platform for users who want more control over their memories, metadata, and backups. However, like any media-heavy application, it can run into problems related to storage limits, sync failures, and slow or broken image loading. Understanding the most common causes helps administrators and home server users keep Immich reliable, fast, and easy to maintain.
TLDR: Most Immich storage, sync, and image loading errors come from limited disk space, incorrect folder permissions, database issues, reverse proxy misconfiguration, or overloaded background jobs. The best solutions include checking storage paths, fixing file ownership, reviewing logs, optimizing thumbnails, and ensuring Redis, PostgreSQL, and workers are healthy. A properly configured backup plan, stable network, and regular updates greatly reduce recurring Immich problems.
Understanding Why Immich Errors Happen
Immich depends on several moving parts: the server application, database, Redis, machine learning services, background workers, uploaded media files, and thumbnail generation. When one part fails, the issue may appear as a storage error, missing photo, broken thumbnail, upload failure, or stalled sync. For example, a photo may upload correctly, but if the background worker cannot generate a thumbnail, the user may see a blank preview or loading spinner.
Before applying fixes, the administrator should identify where the problem occurs. A storage issue usually appears as failed uploads, missing files, or disk space warnings. A sync issue may show incomplete mobile uploads, duplicate assets, or stuck upload queues. Image loading errors often involve thumbnails, permissions, reverse proxy settings, or browser caching.
1. Fixing Immich Storage Errors
Storage errors are among the most common Immich problems because photos and videos grow quickly. A single mobile library can contain hundreds of gigabytes of files, especially if videos, RAW photos, or live photos are included.
Check Available Disk Space
The first step is to confirm that the storage volume has enough free space. Immich may fail uploads when the main drive, upload directory, database volume, or Docker volume becomes full. On Linux systems, administrators commonly check disk space with commands such as df -h and inspect large folders with du -sh.
- Media upload directory: Stores original photos and videos.
- Database volume: Stores metadata, user information, and asset references.
- Thumbnail and encoded video folders: Store generated previews and optimized media.
- Temporary folders: May fill up during upload or transcoding operations.
If disk space is nearly full, the best solution is to move the Immich library to a larger drive, add network storage, or clean up unused files only after confirming they are not required by Immich. Manual deletion inside Immich storage folders should be done carefully because the database may still reference those files.
Verify Storage Path Configuration
Incorrect Docker volume mappings can cause Immich to save files in an unexpected location or lose access after a restart. The administrator should review the Docker Compose file and confirm that the upload location points to the intended host directory. If the path changes, Immich may appear to lose images even though the files still exist elsewhere.
A stable configuration should use absolute paths and persistent volumes. Relative paths can work, but they may cause confusion if Docker Compose is run from a different directory. For long-term reliability, a clearly named storage path such as /mnt/photos/immich/upload is easier to maintain.
Correct File Ownership and Permissions
Permission problems can prevent Immich from reading, writing, moving, or deleting assets. This is especially common after restoring from backup, moving storage to a new disk, or switching from local storage to a NAS.
The Immich containers must have permission to access the upload directory. The correct user and group depend on the deployment method, but administrators should ensure that the container user can read and write to all required directories. If a NAS is used, NFS or SMB permissions must also allow the Docker host to access the files reliably.
2. Solving Sync Problems in Immich
Sync errors often appear in the Immich mobile app when uploads are stuck, repeatedly retrying, or missing from the web interface. The cause may be the phone, server, network, background task settings, or reverse proxy.
Check Mobile App Backup Settings
The mobile app may not sync if background activity is restricted by the operating system. On many phones, battery optimization can pause uploads when the app is not active. The user should allow background activity, disable aggressive battery saving for Immich, and confirm that backup is enabled for the correct albums.
- On Android: Battery optimization may need to be disabled for Immich.
- On iOS: Background app refresh and photo permissions should be checked.
- On both platforms: The selected backup albums should be reviewed.
If sync works only while the app is open, the issue is usually related to mobile operating system restrictions rather than the server itself.
Review Reverse Proxy and Upload Limits
When Immich is placed behind a reverse proxy such as Nginx, Caddy, Traefik, or a tunnel service, upload limits can block large files. Videos may fail while smaller photos upload successfully. The proxy should allow large request bodies and long upload durations.
Administrators should check settings related to maximum upload size, request timeout, buffer size, and websocket support. If a proxy interrupts the connection, the mobile app may show repeated sync attempts or unexplained upload failures.
Confirm Server URL Consistency
Immich clients should connect to a stable and correct server URL. If the mobile app uses an internal IP address while the web interface uses a public domain, sync may behave inconsistently when the user moves between home Wi-Fi and mobile data. A properly configured domain with HTTPS is usually the best option.
The administrator should also verify that the external URL configured in Immich matches the address used by clients. Incorrect URLs can affect sharing, thumbnails, API calls, and background communication.
Restart Stuck Jobs Safely
Some sync problems are caused by stuck background jobs. Immich uses queues for thumbnail generation, metadata extraction, video encoding, library scanning, and other tasks. If Redis or workers become unhealthy, assets may upload but never finish processing.
A safe restart of the Immich stack often clears temporary queue issues. However, if the same problem returns, logs should be reviewed. Repeated crashes may indicate memory pressure, incompatible versions, database connectivity issues, or a corrupted file that causes a worker to fail.
3. Fixing Image Loading and Thumbnail Errors
Image loading errors may appear as gray boxes, broken thumbnails, slow previews, or images that load only after a long delay. These problems can come from missing generated files, slow storage, proxy caching, browser cache issues, or failed jobs.
Regenerate Thumbnails
If original files exist but previews are missing, thumbnail generation may have failed. Immich provides administrative jobs that can regenerate thumbnails and refresh metadata. Running these jobs can fix blank previews after a restore, migration, or version upgrade.
Administrators should avoid running every heavy job at once on low-powered hardware. Thumbnail generation and video transcoding can consume significant CPU, memory, and disk I/O. On small servers, it is better to run jobs gradually and monitor system load.
Check Original File Availability
Sometimes the problem is not the thumbnail but the original asset. If files were moved, deleted, or stored on an unavailable network mount, Immich may still show metadata while failing to load the image. The administrator should verify that the file path exists and that the container can read it.
This issue is common when external libraries, NAS mounts, or removable drives are involved. For important collections, storage should mount automatically at boot before Immich starts. Otherwise, Immich may start successfully while its media directory is unavailable.
Improve Disk and Network Performance
Large photo libraries perform best on reliable storage with good random read performance. Slow external drives, overloaded NAS devices, or unstable Wi-Fi can make Immich feel broken even when the configuration is technically correct. Thumbnails should ideally be stored on fast local storage, while originals may be kept on larger disks or network storage if properly configured.
4. Database and Redis Health Checks
Immich relies heavily on PostgreSQL and Redis. The database stores asset metadata, users, albums, face recognition information, and job references. Redis supports queues and background processing. If either service is unhealthy, many unrelated symptoms can appear.
The administrator should inspect container logs for connection errors, authentication failures, out-of-memory messages, or repeated restarts. A PostgreSQL issue may cause missing assets, failed login, or broken searches. A Redis issue may cause jobs to stall and thumbnails to stop processing.
Regular database backups are essential. A proper backup should include both the database and the media files. Backing up only the upload directory is not enough because Immich needs the database to understand ownership, albums, metadata, and asset relationships.
5. Update Immich Carefully
Immich develops quickly, and updates often include bug fixes, performance improvements, and database migrations. Running a very old version can cause compatibility problems with the mobile app or known image processing bugs. However, updates should be handled carefully because Immich may include breaking changes.
Before updating, administrators should read release notes, back up the database, back up the Docker Compose file, and confirm that media files are safe. After updating, they should check logs and run any recommended migration or administrative jobs. If an update causes image loading or sync problems, logs usually provide the fastest path to the cause.
6. Best Practices to Prevent Future Errors
- Use reliable storage: Avoid nearly full disks and unstable removable drives.
- Monitor free space: Set alerts before the storage volume reaches critical levels.
- Keep backups: Back up both PostgreSQL data and uploaded media.
- Use HTTPS: A stable domain with valid SSL helps mobile sync and sharing.
- Review logs regularly: Logs reveal failing workers, permission errors, and proxy problems.
- Limit heavy jobs: Run thumbnail and video jobs when the server has available resources.
- Document paths: Clear storage documentation prevents confusion during migration.
The most reliable Immich installations are treated like small production systems. Even for a home server, predictable storage, backups, monitoring, and staged updates make a major difference. When errors occur, the best approach is to isolate the layer involved: storage, database, proxy, mobile client, or background worker.
FAQ
Why are Immich uploads failing even though the server is running?
Uploads often fail because the storage volume is full, the upload folder has incorrect permissions, or a reverse proxy is blocking large files. The administrator should check disk space, Docker volume paths, permissions, and proxy upload limits.
Why does Immich show photos but not load the images?
This usually means the database still has asset records, but the original files or thumbnails are unavailable. The cause may be missing storage, failed thumbnail generation, permission problems, or an unmounted network drive.
How can stuck mobile sync be fixed?
The user should confirm that backup is enabled, selected albums are correct, background activity is allowed, and the server URL is stable. If those settings are correct, the administrator should inspect server logs and reverse proxy limits.
Is it safe to delete files directly from the Immich upload folder?
Direct deletion is not recommended because the database may still reference those files. Assets should normally be deleted through Immich. If manual cleanup is required, a backup should be created first.
Why are thumbnails missing after restoring a backup?
Thumbnails may not have been included in the backup, or permissions may have changed during restoration. Regenerating thumbnails through Immich administrative jobs usually resolves the issue if the original files are available.
What should be backed up in an Immich installation?
A complete backup should include the PostgreSQL database, uploaded media files, configuration files, and any custom storage paths. Without the database, albums, users, metadata, and asset relationships may be lost.
Can Immich use a NAS for storage?
Yes, Immich can use NAS storage, but the mount must be reliable, permissions must be correct, and the storage should be available before Immich starts. Slow or unstable network storage may cause loading delays or processing failures.