How to Restore Immich After a Failed Container Update
Restore Immich after a failed container update by freezing the current evidence, pinning every Immich service to the last known-good release, and restoring data only if a coordinated rollback cannot start the stack.
An update can change application code, database schema expectations, environment variables, and companion-service versions at once. Repeatedly pulling latest or mixing old and new containers makes the recovery boundary harder to see. Save the Compose file, environment, logs, database, and upload paths before acting, then choose between an image rollback and a full database-plus-library restore.
Freeze the Failed State and Identify the Update Boundary
Stop automatic restarts and record the exact images or digests for the server, machine-learning, database, and cache services. Save startup logs and the deployment files before another pull. Pass means you can name what changed; fail means recovery should pause until the old versions can be identified from deployment history or local images.
Check whether the server exits before connecting to the database, during a migration, or after becoming ready. A dependency connection error maps to network, credential, or health repair; a migration error raises the risk of restoring only the app image because the database may already have changed.
A walkthrough of versioned Immich updates shows why the release boundary and deployment files matter. Use it to inventory the transition, while treating your own logs and backups as the authority for rollback.
Try a Complete Last-Known-Good Image Rollback First
Pin all Immich application images to the exact previously working release rather than changing one service alone. Recreate the affected containers while leaving persistent volumes untouched. If the stack becomes healthy and the logs show no schema incompatibility, this low-change rollback passes.
If the old server refuses the current database schema, stop. Do not alternate versions against the same database or manually edit migration tables. That failure means the update crossed a data boundary and recovery must use a database backup whose timestamp matches the selected application release.
An Immich v1.135.3 report documents a specific database-migration startup failure after an update. Its bounded migration example justifies reading the first fatal error carefully; it is not permission to copy that case's commands into another version.
Restore Database and Media Only When Rollback Cannot Recover
Create a safety copy or storage snapshot of the failed state before restoring. Build a clean recovery target, restore the database backup, then expose the corresponding upload library and required deployment files. Do not overwrite the only current library with an older copy merely to align timestamps.
Database records and asset files must describe the same collection. If the backup predates recent uploads, preserve those newer files separately for later reconciliation. A restore passes when migrations complete, expected users and assets appear, and sampled originals open without widespread missing-file errors.
The ZimaSpace Immich migration guide provides a useful inventory for moving persistent components without treating a container image as the photo library itself.
Validate Recovery Before Attempting the Update Again
Test login, timeline browsing, original download, thumbnail generation, Smart Search, face processing, one new upload, and one database backup. Restart the containers and host once. Pass requires the same assets and functions after restart with no repeating migration or permission errors.
Keep the failed and recovered states separately labeled until validation ends. If recovery depends on an older version, disable unattended image pulls and document the pin. Re-attempt the update only after reviewing every intervening release and taking a fresh coordinated backup.
Roll back to the preserved recovery target if a new upload disappears, originals fail to open, or jobs repeatedly crash. Escalate with source and target versions, image digests, first fatal log, database backup timestamp, and storage mapping; never retire the last known-good copy while update compatibility remains unresolved.
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.
