When Should You Rebuild Rather Than Repair an Immich Installation?
Repair Immich when the failure is localized and the persistent data is demonstrably intact; rebuild the runtime when configuration drift is broad but a verified database, media library, deployment definition, and rollback copy can recreate the service safely.
Rebuild is not the same as deleting everything. Containers and networks are disposable, while the database and originals are the record of the library. First classify integrity, scope, and reproducibility. If the only database or only copy of photos may be damaged, preserve it and stopโstarting clean over that evidence can turn a diagnosable incident into permanent loss.
Repair When the Fault Is Localized and Reversible
Prefer repair when one mount, permission, environment value, dependency, job, or pinned image explains the failure and the system behaved normally before a known change. Capture logs, make a backup, change that single layer, and repeat the trigger.
A pass restores the failed function without creating missing assets, database errors, or new startup warnings. If the same fault returns after recreation, the cause may live in the deployment definition or persistent state, so repeated container replacement is no longer evidence-based repair.
A database-corruption discussion illustrates how quickly recovery choices become high risk when the database is the suspected layer. Use the preserve-before-repair lesson, not any unverified destructive command.
Rebuild the Runtime When Drift Is Unbounded
Choose a clean runtime rebuild when image versions, networks, environment values, mounts, and manual container changes can no longer be reproduced, but verified persistent components remain intact. Build beside the old instance with pinned versions and isolated ports rather than erasing it.
A rebuild is also appropriate after host compromise or an unsupported installation accumulates unknown changes, because restoring trusted deployment inputs creates a new audit boundary. Rotate exposed credentials and inspect backups before attaching them to the clean target.
The ZimaSpace overview of self-hosted app deployment provides broader service-stack context; Immich still requires its database and media relationship to be validated independently.
Do Not Rebuild Over Uncertain Persistent Data
Stop when the database and upload library may be out of sync, the only backup has not been tested, or the authoritative copy is unclear. Snapshot or clone all candidates and record timestamps before attempting database recovery or media reconciliation.
An Unraid recovery thread shows the operational difficulty of restoring Immich when backup components and versions do not line up. Its restore-boundary discussion supports testing in isolation rather than overwriting the production paths.
If originals are intact but the database is unrecoverable, preserve both and document the consequence before considering a new library import. That is a data-reconstruction decision, not routine repair, and it may lose albums, sharing state, faces, favorites, or historical metadata.
Validate Persistent Data on a Clean Target
Restore or attach copied persistent data to the clean target, then test users, timeline counts, sampled originals, albums, search, face data, external libraries, a new upload, jobs, and a fresh database backup. Compare results with the preserved source evidence.
Compare database asset counts with sampled files across several dates, users, and media types. Confirm external-library paths, derived jobs, and a new database dump before assigning the production address. A login screen alone does not prove data integrity.
Restart containers and host twice. Pass requires stable mounts, repeatable configuration, no migration loop, and the original workload. If the clean target reproduces the same database or file error, runtime drift was not the cause and specialist data recovery remains the safer branch.
Cut Over With a Rollback Boundary
Transfer the production address only after the isolated checks pass, and keep the old system powered off but recoverable through an agreed observation period. Prevent both instances from accepting uploads or serving the same automation at once.
Run the normal family upload, browse, search, sharing, and backup workflow after cutover. A pass preserves counts and originals across the next restart; a mismatch sends traffic back to the preserved target without overwriting either dataset.
Return to repair or specialist recovery if the clean target reproduces the same database or file errors; the runtime was not the cause. Roll back cutover if counts or originals differ. Escalate with versions, checksums, backup timestamps, first error, and the exact boundary between copied and newly created state.
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.
