How to Roll Back or Recover After a Failed Immich Server Update

Rate this AI Tool

An Immich server update should be treated with the same care as any production data service upgrade. Immich stores irreplaceable photo and video metadata, database records, thumbnails, encoded media, user accounts, and configuration details, so a failed update is not just an inconvenience. The safest recovery depends on whether the update failed before or after database migrations, whether you have a recent backup, and whether your media files are still intact.

TLDR: Stop the Immich containers first, avoid repeated restarts, and preserve the current state before making changes. If you have a known-good backup, restore the database and Immich storage together, then pin Docker images to the last working Immich version. If no backup exists, do not blindly downgrade after a database migration; review logs, check release notes, and consider fixing forward to the intended version. Always verify user login, asset counts, uploads, thumbnails, and mobile sync before declaring the recovery complete.

1. Stop and Stabilize the Server

When an Immich update fails, the first priority is to stop the system from making the situation worse. A container that continuously restarts may keep retrying migrations, writing partial logs, or creating inconsistent derived files. Do not immediately run another update, prune Docker volumes, or delete containers in an attempt to “clean things up.”

From the directory that contains your Immich docker-compose.yml file, stop the stack:

docker compose down

If your deployment uses the older command syntax, use:

docker-compose down

Then record basic information about the failed update. Note the version you were running before, the version you attempted to install, the operating system, and whether you changed the compose file, environment variables, database version, or storage paths. This information will matter if you need to restore, roll back, or ask for help.

2. Collect Logs Before Changing Anything

Logs help distinguish between a container image problem, a missing environment variable, a database migration failure, storage permission issues, or a version mismatch between Immich services. Bring the stack up only if needed to capture logs, then stop it again.

docker compose logs --tail=300 immich-server
docker compose logs --tail=300 immich-machine-learning
docker compose logs --tail=300 database
docker compose logs --tail=300 redis

Look carefully for messages containing migration, permission denied, relation does not exist, password authentication failed, connection refused, or unsupported version. These phrases often reveal whether the update broke because of the application, the database, the file system, or the configuration.

If you use a reverse proxy such as Nginx Proxy Manager, Traefik, Caddy, or Apache, also check whether the Immich containers are actually healthy. Sometimes the update succeeded, but the web interface appears broken because the proxy points to the wrong container port or still caches an old route.

3. Preserve the Current State

Before attempting a rollback, make a safety copy of the current database volume and Immich storage directory. Even if the current state is broken, it may contain valuable data added shortly before the update. This is especially important if your mobile clients uploaded new assets during or immediately after the upgrade.

At minimum, preserve the following:

  • Database volume or dump, usually PostgreSQL data used by Immich.
  • Upload or library directory, where original photos and videos are stored.
  • Thumbs, encoded video, profile, and library-related folders, depending on your Immich storage layout.
  • Configuration files, including docker-compose.yml, .env, reverse proxy configuration, and any custom storage mappings.

If you can access PostgreSQL, create a database dump. Container names vary, but the command may look similar to this:

docker compose exec database pg_dumpall -U postgres > immich-current-state.sql

If the database container cannot start, copy the Docker volume or snapshot the disk at the host level. Avoid running docker system prune --volumes, because it can permanently remove database data.

4. Decide: Restore, Roll Back, or Fix Forward

The correct recovery path depends on the condition of the database. Immich updates may include database migrations. Once a migration has run, returning to an older application version may not be safe unless the database is also restored to its earlier state. Application rollback without database rollback is only safe when the database schema remains compatible.

Use this decision model:

  • If you have a full backup from before the update: restore the backup and run the last known working Immich version.
  • If the update failed before migrations completed: a rollback may work, but still proceed cautiously.
  • If migrations completed and the old version will not start: restore the old database backup, or fix forward to the new version.
  • If originals are intact but the database is damaged: recovery may involve database restore, re-import strategies, or manual repair, depending on your backup quality.

5. Restore From a Known-Good Backup

A full restore is the most reliable way to recover after a failed Immich update. Ideally, your backup includes both the PostgreSQL database and the Immich storage directory from the same point in time. Restoring only the files without the database, or only the database without the files, can cause missing assets, broken thumbnails, or inconsistent metadata.

First, keep the stack stopped:

docker compose down

Next, restore your Immich storage directory from backup. The exact command depends on your backup tool, but the principle is simple: restore the original media and Immich-managed folders to the same paths referenced in your compose file.

Then restore PostgreSQL. If you backed up using a SQL dump, you normally start the database container, create or clean the target database as appropriate, and import the dump. For example:

docker compose up -d database
cat immich-backup.sql | docker compose exec -T database psql -U postgres

If your backup is a volume-level backup, restore the PostgreSQL volume while the database container is stopped. Be careful with ownership and permissions, because PostgreSQL is strict about its data directory.

Finally, set Immich to the last working version. In many Docker Compose deployments, this is controlled by IMMICH_VERSION in the .env file. Avoid vague tags such as latest. Use a specific previous version that you know worked.

IMMICH_VERSION=v1.xxx.x

Pull and start the pinned version:

docker compose pull
docker compose up -d

Wait for the containers to become healthy, then review logs again. Do not assume the restore succeeded just because the web page loads.

6. Roll Back Containers Without Restoring the Database

This approach is riskier and should only be used when you are confident that the database schema was not changed in a way that breaks compatibility. For example, if the failed update happened because an image could not download, an environment variable was invalid, or the server container crashed before migrations began, pinning the old image may be enough.

Edit your .env file and set the previous working Immich version. Make sure all Immich application containers use the same release family. Mismatched versions can produce confusing errors.

IMMICH_VERSION=v1.xxx.x

Then pull and start:

docker compose pull
docker compose up -d

Watch the logs closely:

docker compose logs -f immich-server

If the old version reports database schema errors, stop immediately. That usually means the newer version already modified the database. At that point, restore the database backup or move forward to a compatible newer release rather than repeatedly trying older images.

7. Fix Forward When Rollback Is Unsafe

Sometimes the safest recovery is not a rollback. If the database has already been migrated, the most practical solution may be to correct the cause of the failed update and continue running the newer Immich version.

Common fix-forward actions include:

  • Update your compose file to match the official Immich release requirements.
  • Review the release notes for breaking changes, renamed variables, or required manual steps.
  • Confirm PostgreSQL compatibility, especially if the release changed database expectations.
  • Check storage permissions for mounted directories used by uploads, thumbnails, and encoded videos.
  • Verify environment variables such as database host, username, password, upload location, and external URL.
  • Ensure all images are updated together, rather than mixing old and new Immich services.

If logs show missing columns, failed migrations, or schema conflicts, do not manually edit the database unless you fully understand the migration path. Manual changes can make future upgrades more difficult. In serious cases, preserve the current state and seek assistance from Immich documentation, release notes, or experienced administrators.

8. Verify the Recovery Thoroughly

After restoring or rolling back, perform a structured validation. A superficial check is not enough for a photo management server.

  • Confirm that all containers are running and healthy.
  • Log in with an administrator account and a normal user account.
  • Check the total asset count against your expected number.
  • Open several older and newer photos and videos.
  • Confirm thumbnails, previews, and encoded videos display correctly.
  • Test search, albums, people, shared links, and timeline navigation.
  • Upload a small test image from the web interface.
  • Test mobile app backup only after the server appears stable.

If the mobile app was connected during the failed update, open it carefully and confirm it is not repeatedly retrying uploads that already exist. Duplicate uploads can occur if clients lose track of server state during an outage.

9. Prevent the Same Problem Next Time

The best recovery plan is one you prepare before the next Immich update. Treat every update as a change that can affect the application, database, and stored media. A disciplined update process reduces both downtime and data risk.

  • Pin versions instead of using latest or automatic unattended updates.
  • Read release notes before upgrading, especially for breaking changes.
  • Back up the database and storage together before every update.
  • Test restores periodically; an untested backup is only an assumption.
  • Keep a copy of the previous compose file and .env.
  • Update during a maintenance window, not while phones are actively uploading large libraries.
  • Snapshot the host or VM if your platform supports reliable snapshots.

A sensible update workflow is: stop mobile uploads, create backups, snapshot the server, read release notes, pin the target version, pull images, start the stack, watch migrations, and validate the library. If anything goes wrong, you will have a clean path back.

Final Thoughts

Recovering from a failed Immich update requires patience and discipline. The most important rule is to protect the database and original media before taking corrective action. A rollback is straightforward only when the database remains compatible or when you restore both the database and files from a matching backup. If migrations have already changed the database, fixing forward may be safer than forcing an older version to run.

Immich is a powerful self-hosted photo platform, but it should be managed like critical infrastructure. With version pinning, reliable backups, careful verification, and a calm recovery process, most failed updates can be resolved without losing photos, videos, or metadata.