Immich is a self-hosted photo and video management solution often favored for its flexibility and open-source nature. However, users frequently encounter the "Error Loading Image" issue, which can disrupt the functionality of the platform. This guide addresses common causes of the error, steps to troubleshoot, and practical solutions to restore your Immich setup.

Common Causes of the "Error Loading Image" Issue

1. Incorrect File Paths:
   • Moving or renaming the photo storage location can lead to broken file paths.
   • Immich fails to locate images if the configured paths in the docker-compose.yml or .env file are incorrect.
2. Thumbnail Generation Problems:
   • Missing or incomplete thumbnail files often cause images to appear as broken.
   • This issue frequently occurs during migrations or after updates.
3. Version Compatibility Issues:
   • Certain Immich versions, such as v1.113.0, have been reported to cause thumbnail or file-access issues.
   • Reverting to a stable version often resolves such problems.
4. Corrupted or Missing Files:
   • Images that are partially uploaded or removed without proper synchronization result in errors.
   • Using external libraries (e.g., from WhatsApp or Google Photos) can exacerbate these issues.
5. Container Misconfigurations:
   • Deprecated or orphaned containers (e.g., immich_microservices) might still run, causing conflicts.
   • Outdated configurations in the docker-compose.yml file can also contribute.

Step-by-Step Troubleshooting

1. Verify Storage Paths

• Check the paths for uploaded images and thumbnails in your docker-compose.yml and .env files. For example:

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

• Ensure the UPLOAD_LOCATION and THUMB_LOCATION directories exist and contain the necessary files.

2. Refresh Thumbnails

• Log in to Immich's admin interface and navigate to Administration > Jobs.
• Run the Generate Thumbnails job for all images.

docker exec -it immich_server npm run job:generate-thumbnails

• This can fix missing or corrupted thumbnail files.

3. Restart and Rebuild Containers

• Use the following commands to rebuild your Immich setup:

docker compose down
docker container prune -f
docker compose up -d --remove-orphans

• This ensures any outdated or conflicting containers are removed.

4. Revert to a Stable Version

• If the issue persists, consider reverting to a previous stable version:

IMMICH_VERSION=v1.112.1
docker compose pull
docker compose up -d

• Update the IMMICH_VERSION in your .env file and redeploy the containers.

5. Address File Corruption

• If files are corrupted or partially uploaded:
  • Verify the original files exist in the upload directory.
  • Re-upload missing or incomplete files using Immich's web or mobile app.
• For external libraries, ensure they are correctly mounted and accessible by the Immich server.

6. Remove Deprecated Containers

• If your setup includes deprecated containers (e.g., immich_microservices), stop and remove them:

docker stop immich_microservices
docker rm immich_microservices
docker compose up -d

Advanced Fixes

Custom Thumbnail Storage

If the thumbnail directory has been moved or reconfigured:

1. Update the THUMB_LOCATION in your .env file:

THUMB_LOCATION=/new/path/to/thumbnails

2. Delete old thumbnails and regenerate:

docker exec -it immich_server rm -rf /usr/src/app/upload/thumbs
docker exec -it immich_server npm run job:generate-thumbnails

Fix for External Libraries

For images imported from external libraries (e.g., Google Photos or WhatsApp):

Ensure permissions are correctly set:

chmod -R 755 /path/to/external/library

Remount the library if necessary:

docker volume rm immich_library
docker volume create --name immich_library -o device=/path/to/external/library

Preventing Future Issues

1. Maintain Backups:
   • Regularly back up the UPLOAD_LOCATION, DB_DATA_LOCATION, and thumbnails directory to avoid data loss.
2. Monitor Jobs:
   • Frequently check the Administration > Jobs page to ensure all jobs, especially thumbnail generation, are completed.
3. Keep Software Updated:
   • Stay updated with the latest stable version of Immich, Redis, and PostgreSQL.
4. Avoid Deprecated Containers:
   • Remove any unused or deprecated containers during updates or migrations using the --remove-orphans flag.

Real-World Examples

1. Version Conflict Resolution‍

A user on v1.113.0 faced persistent thumbnail issues. Reverting to v1.112.1 resolved the problem after refreshing thumbnails.

2. Fixing Orphaned Containers

A deprecated immich_microservices container caused errors. Stopping and removing it with:

docker stop immich_microservices
docker rm immich_microservices

followed by a full rebuild, fixed the issue.

3. Corrupted Thumbnail Recovery

Missing thumbnails in the thumbs directory were fixed by deleting the folder and regenerating all thumbnails:

docker exec -it immich_server npm run job:generate-thumbnails

Conclusion

The "Error Loading Image" issue in Immich is usually related to incorrect file paths, missing thumbnails, or version conflicts. By following the troubleshooting steps outlined above, you can quickly identify and resolve the root cause. Remember to maintain regular backups and stay updated with the latest stable version to prevent future problems.

With Immich's flexible architecture and open-source nature, most issues can be addressed with a little patience and careful configuration.