How to Roll Back Immich Safely After an Incompatible Release
Roll back Immich only after preserving the current state and determining whether the newer release changed the database or configuration in a way the older image cannot read.
A container image is replaceable, but its persistent state may already have been migrated. If an upgrade starts badly, stop automatic updates and new writes, record both versions, protect the current database and media, then choose between a simple image rollback and a restore of the pre-upgrade recovery point.
Freeze the Failed Upgrade Before It Changes More State
Disable automatic image updates and stop clients from adding new photos while you collect evidence. Record the exact old and new Immich image versions or digests, PostgreSQL version, Compose and environment files, mount paths, and the first startup or migration error.
The ZimaSpace guide to container rollback boundaries makes the critical distinction: persistent volumes survive image replacement, but that is safe only when the older application remains compatible with the state inside them.
Take a database-native backup of the current failed state if the database can be read, and preserve the pre-upgrade backup separately. Do not overwrite either with repeated experiments. The current copy may be needed to move forward later even if the immediate goal is to return to the older version.
Determine Whether the Release Crossed a Database Migration Boundary
Look at the first failure after upgrade and identify whether it occurs before or during database migration, after migration while the application starts, or only during a user workflow. This timing changes the rollback plan because an older image may not understand a schema already changed by the newer release.
A recent Immich report where the service failed after an upgrade path illustrates why unsupported or skipped migration paths can make simple version swapping unreliable. Treat the thread as a case study and verify the exact migration sequence for your versions.
If the newer application never touched the database and the failure is limited to image or runtime compatibility, a pinned image rollback may be enough. If migrations completed, assume the pre-upgrade database backup is the safer partner for the old image unless you have explicit compatibility evidence.
Restore a Matching Database and Runtime Instead of Mixing Eras
Build the rollback target from the last known-good application version, its compatible deployment configuration, and the database recovery point from before the incompatible change. Keep the media tree intact unless the release changed media files in a documented way; do not recopy terabytes merely because the application image changed.
The database rollback discussion from database-compatible rollback planning explains the general danger of deploying older code against a schema it no longer understands. That principle is more important than whether the container itself starts successfully.
Start the rollback instance in isolation so mobile clients and scheduled jobs cannot write until validation finishes. If the old version immediately reports schema errors, stop. Do not force migrations backward manually on the only database copy unless you have a tested, version-specific recovery procedure.
Pin the Exact Known-Good Image and Reproduce Its Configuration
Use a specific version or immutable image reference rather than a moving tag. Restore the matching environment, service dependencies, device mappings, networks, ports, and reverse-proxy target from the last known-good deployment. A rollback that silently changes several infrastructure layers creates a second incident.
Preserve the failed newer image and configuration beside the rollback notes. This makes a controlled forward recovery possible after the incompatibility is understood. Removing every new artifact immediately can make it harder to compare the failed and working states or reproduce the upgrade in a test environment.
If the older service starts against the restored state, inspect logs before enabling clients. Confirm there is no unexpected migration attempt, fresh-install initialization, missing storage mount, or permission rewrite. A login page alone is not proof that the rollback is using the intended data.
Validate the Old Version Under the Original Trigger and Keep a Forward Path
Test representative users, old and recent assets, albums, sharing, search, one new controlled upload, background jobs, database backup creation, and the reverse-proxy route. Restart the stack once and confirm the same mounts and database return without manual intervention.
Keep new uploads paused until those checks pass, then reopen access and watch the normal workload window. Preserve both the pre-upgrade backup and the failed-newer-state backup so you can retry the upgrade later in an isolated copy after the compatibility issue is understood.
Rollback has failed if the older version reports schema incompatibility, known data is missing, or writes land on an unexpected path. Stop and restore the preserved recovery point again rather than layering repairs. Escalate with exact versions, migration logs, database backup timestamps, Compose diff, and the first verification step that fails.
Recommended products
Support & Tips
More to Read
How to Optimize Immich Database Connections for Concurrent Containers
Do not raise max_connections first. Measure Immich sessions, total every container's demand, preserve admin headroom, and tune only the proven bottleneck.
How to Prevent Duplicate Jobs or Imports in Immich
Separate repeated jobs from duplicate assets. Use one canonical ingestion path, control retries and path changes, then test re-entry on a small cohort.
How to Repair Immich After Its Database Volume Fills Up
Never delete PostgreSQL WAL to free space. Stop Immich writes, preserve database state, add safe capacity, recover PostgreSQL, then prevent recurrence.
