Updating an Immich server on Docker is usually straightforward, but when something goes wrong it can affect access to your photo library, background jobs, thumbnails, database connectivity, or machine learning features. Because Immich is under active development, updates may include database migrations, container image changes, environment variable updates, and breaking configuration changes. The safest way to troubleshoot is to work methodically: verify your configuration, inspect logs, confirm service health, and avoid making destructive changes until you understand the cause.

TLDR: If Immich breaks after a Docker update, first check the official release notes, confirm your docker-compose.yml and .env files match the current version, and review container logs. Then restart the stack, verify database migrations completed, and make sure Redis, PostgreSQL, machine learning, and server containers are healthy. If the issue persists, restore from backup or roll back to the previous working version while preserving your uploads and database volumes.

Start by Confirming What Changed

Before changing settings or deleting containers, identify exactly what was updated. A broken Immich deployment may be caused by a new Immich image, a modified Docker Compose file, a changed environment variable, a database migration, or even a Docker Engine update on the host system. Treat the problem as an investigation rather than a simple restart issue.

Begin by checking the Immich release notes for the version you installed. Look specifically for sections labeled breaking changes, migration notes, Docker Compose changes, or required environment variables. Immich evolves quickly, and older compose files may continue working for a while before failing after a specific release.

You should also record your current versions. Run commands similar to the following from your Immich directory:

• docker compose ps to see which containers are running.
• docker compose images to verify image versions.
• docker compose logs --tail=100 immich-server to inspect recent server logs.
• docker compose logs --tail=100 database or postgres to inspect database logs.

Do not delete volumes to “start fresh” unless you are intentionally restoring from backup. Your database volume and upload library are the most important parts of the installation.

Check Container Status and Logs

The fastest way to locate the failing component is to inspect the state of each container. Run:

docker compose ps

Look for containers that are restarting, unhealthy, or exited. A typical Immich deployment may include services such as immich-server, immich-machine-learning, redis, and database. Depending on your version and setup, names may vary.

If the server container is constantly restarting, pull its logs:

docker compose logs immich-server

Common log messages may point to database connection errors, missing environment variables, failed migrations, permission problems, or incompatible configuration. If PostgreSQL is failing, inspect database logs next. If Redis is unavailable, Immich may start but behave unpredictably, especially with queues and background tasks.

When reading logs, focus on the first meaningful error rather than the final line. Later errors are often consequences of the original failure. For example, if the database cannot authenticate, Immich may display many secondary errors related to migrations or unavailable repositories.

Review Your Docker Compose and Environment Files

After an update, one of the most common causes of failure is an outdated docker-compose.yml or .env file. If you originally installed Immich months ago, your configuration may no longer match the recommended deployment template.

Compare your files with the current official example. Pay attention to:

• Image names and tags: Confirm that all Immich services use compatible versions.
• Database image version: PostgreSQL version changes should be handled carefully.
• Environment variables: New required variables may have been added.
• Volume mappings: Verify that uploads and database data point to the correct host paths or named volumes.
• Network configuration: Ensure services can communicate using expected container names.
• Port mappings: Confirm the web interface is exposed on the correct host port.

If you customize your compose file, apply changes carefully instead of replacing everything blindly. Your upload location, database path, and external reverse proxy configuration may be specific to your server.

A safe workflow is to copy the latest example compose file to a temporary location, compare it line by line with your current file, and merge only the required changes. Tools such as diff can help, but manual review is still important.

Restart the Stack Correctly

Some issues after an update are caused by containers running old images or services starting in the wrong order. A clean restart can help, provided you do not remove persistent volumes.

From your Immich directory, you can typically run:

docker compose pull

docker compose down

docker compose up -d

This stops and recreates containers while keeping named volumes intact. Avoid using commands such as docker compose down -v unless you fully understand the consequences. The -v flag removes volumes, which can delete your database if it is stored in a named Docker volume.

After restarting, check status again:

docker compose ps

Then view logs:

docker compose logs -f

Be patient during the first start after an update. Database migrations and background indexing may take time, especially on large libraries or slower hardware.

Verify Database Health and Migrations

The PostgreSQL database is central to Immich. It stores metadata, users, albums, asset records, job status, and other application state. If the database is unavailable or migrations fail, the Immich web interface may not load or may show server errors.

Common database-related symptoms include:

• The Immich server container exits immediately after startup.
• Logs show authentication failures or connection refused errors.
• The web interface loads but assets, albums, or users are missing.
• Migration errors appear in the server logs.

Check that the database container is running and healthy. If you changed database passwords, usernames, hostnames, or volume paths, confirm that the values in your .env file match the actual database configuration. A mismatch between the database password in PostgreSQL and the password used by Immich is a frequent cause of failed updates.

If migrations failed, do not manually edit database tables unless you are experienced and have a verified backup. Instead, read the exact migration error, search the release notes, and confirm that you did not skip required upgrade steps. Some applications support only sequential upgrades across major changes, and jumping across many versions can increase risk.

Check File Permissions and Upload Paths

After updates, permission problems may appear if container users changed, host directories were moved, or files were restored from backup using a different user account. Immich must be able to read and write to the upload location, thumbnails, encoded video files, and related storage paths.

If the web interface opens but uploads fail, thumbnails do not generate, or existing images appear broken, inspect the mapped upload directory. Confirm that the directory exists on the host and that Docker is mounting it into the container as expected.

Useful checks include:

• Confirm the host path in docker-compose.yml is correct.
• Verify the disk is mounted if you store photos on an external drive or NAS.
• Check that the filesystem is not read-only.
• Ensure there is enough free disk space.
• Review permissions and ownership on the upload directory.

Storage problems can be mistaken for application bugs. If Immich cannot access files, the database may still list assets, but the actual images or videos will not render correctly.

Address Machine Learning and Search Problems

After an update, the core Immich server may work while machine learning features fail. This can affect facial recognition, smart search, object detection, and related background tasks. In many Docker installations, machine learning runs as a separate container, so it should be checked independently.

Run:

docker compose logs immich-machine-learning

Look for model download failures, hardware acceleration errors, memory limits, or permission problems. If your server has limited RAM, the machine learning container may be killed by the host during heavy processing. You can confirm this by checking system logs or Docker events.

If search or facial recognition seems incomplete after a successful update, check Immich’s administration page and job queue. Some tasks may need to be re-run after major upgrades. However, avoid repeatedly forcing jobs if the logs show a real service failure. Fix the underlying container issue first.

Inspect Reverse Proxy and HTTPS Configuration

If Immich appears healthy in Docker but is unreachable through your domain, the problem may be your reverse proxy rather than Immich itself. Updates can change internal ports, headers, websocket behavior, or expected paths. This is especially relevant if you use Nginx Proxy Manager, Traefik, Caddy, or a custom Nginx configuration.

Test direct access from the local network using the mapped host port. If direct access works but the domain does not, investigate the proxy. Confirm that:

• The proxy forwards to the correct host and port.
• Websocket support is enabled if required.
• Upload size limits are high enough for large photos and videos.
• TLS certificates are valid and not expired.
• Headers such as X-Forwarded-For and X-Forwarded-Proto are passed correctly.

Large file uploads are a common reverse proxy issue. If small images upload but videos fail, review proxy body size limits and timeout settings.

Clear Browser and Mobile App Confusion

Not every post-update issue is server-side. Browser caching, stale mobile app sessions, or version mismatches between the mobile app and server can cause confusing behavior. If the server logs look healthy but the interface behaves strangely, test with a private browser window or a different device.

Also update the Immich mobile app to a version compatible with your server. If you use automatic server updates but delayed mobile app updates, temporary incompatibilities can occur. Sign out and sign back in only after confirming your server is healthy, because authentication issues can otherwise make troubleshooting harder.

Rollback Safely if Necessary

If the update introduced a serious issue and you need service restored quickly, rolling back may be reasonable. A safe rollback requires that your database is compatible with the older version. This is not always true after migrations have run.

The safest rollback method is restoring a full backup made before the update, including:

• The PostgreSQL database backup or database volume snapshot.
• The upload library directory.
• Your docker-compose.yml file.
• Your .env file.

If you only change the container image tag back to an older version after a database migration, the older Immich version may fail because it does not understand the newer database schema. For this reason, backups are not optional for serious self-hosting. They are the difference between inconvenience and data loss.

Prevent Problems During Future Updates

The best fix is prevention. Immich stores valuable personal data, so updates should be handled with the same care as any important production service. Before updating, create a database backup, confirm your upload directory is protected, and read the release notes. If your instance is important to family members or other users, schedule updates during a quiet period.

A practical update checklist includes:

1. Back up the database and confirm the backup can be restored.
2. Back up configuration files, especially .env and docker-compose.yml.
3. Read release notes for breaking changes.
4. Pull new images with docker compose pull.
5. Restart cleanly using docker compose down and docker compose up -d.
6. Watch logs until migrations and startup complete.
7. Test uploads, search, thumbnails, login, and mobile sync.

For more cautious administrators, consider testing updates on a staging copy of the server first. Even a simple duplicate environment using a recent database backup can reveal migration or configuration issues before they affect the main instance.

Final Thoughts

Fixing Immich after a Docker update requires patience, but most issues can be resolved without data loss if you proceed carefully. Start with logs, compare your configuration against the current recommended setup, verify database and storage health, and check supporting services such as Redis, machine learning, and your reverse proxy. Above all, protect your database and upload files before attempting major changes.

Immich is a powerful self-hosted photo platform, and Docker makes it manageable, but active projects require disciplined maintenance. With reliable backups, careful updates, and systematic troubleshooting, you can keep your photo library available while reducing the risk of unexpected downtime.