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 Match Docker Restart Policies to Databases, Workers, and Web Apps
Match restart policy to service lifecycle and exit semantics. Pair it with health and readiness checks; do not use restart loops to hide dependency...
How to Configure Container User IDs Across Multiple NAS Shares
Map each container's UID/GID to its NAS shares, use shared groups or ACLs where needed, and treat PUID/PGID as image-specificโnot universal Docker settings.
How to Set Up Docker Compose Profiles for Optional Home Server Services
Leave required services unprofiled and use profiles for optional tools. Test direct targets and dependencies instead of assuming a profile starts a full stack.
