# Recovery

[← Documentation index](index.md)

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](stages/renames.md); 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](installation.md#restoring).

## 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.