2.8 KiB
Recovery
What the application resolves by itself, and what needs you. The dividing line is simple: it resumes when the evidence is unambiguous, and it stops and asks when it is not. It never guesses about your files.
An interrupted rename
A rename records its intent before touching the disk, so after a crash the journal plus the actual filesystem give a verdict per operation:
| verdict | means | what happens |
|---|---|---|
| resumable | the move provably did not happen | reset to planned and run again |
| rollback-safe | the move happened; the remaining steps can be completed or undone | drive it forward, or roll it back |
| manual | the evidence is contradictory | left alone, and it keeps blocking |
Open Renames; the recovery panel lists every unresolved
operation and offers a resolve action only where one is safe. Until then, unrelated
mutations are refused with rename_recovery_required — building new work on a
half-applied move is how a library becomes unexplainable.
An uncertain upload
unknown_requires_verification means the uploader died after Immich may have
accepted the files. It is not retryable. Verification asks the server whether it
holds the recorded SHA-1 and answers present, absent, or inconclusive. An
inconclusive answer is resolved by you, with your evidence and name recorded in the
batch's history.
A failed migration
A pending schema change is snapshotted before it is applied. If the upgrade fails,
the previous database and its pre-migration backup are both intact and the error
log names the backup directory. Stop everything and run the
restore drill.
A restored backup
After restoring, run a scan. Paths are reconciled against the real library and
identities are preserved where hashes match. Anything that does not match becomes a
visible stale or divergent state instead of being quietly accepted.
Mount every archive medium the manifest names before archiving again: the database records where archived originals live, it does not contain them.
A job that will not start
Check, in this order: is a worker running; is another mutating job holding the lane
(lock_held); is an interrupted rename blocking everything
(rename_recovery_required); is the library lock held by a process that is still
alive (exit code 2 names the holder).
What is never automatic
No file is deleted, no folder is renamed, no upload is retried, and no archive source is removed without either an explicit confirmation from you or a verification the application performed itself. If you are reading this page because something happened that you did not approve, that is a bug worth reporting — with the diagnostics output and the relevant journal, both of which are safe to share: they carry no secrets.