Restore Immich After Server Failure: Database and Photos

Preserve the surviving backups and record the version

Check: Keep the originals of your database dump, asset backup, docker-compose.yml and .env unchanged. Record the backup date, Immich image version, UPLOAD_LOCATION, external library mounts and database settings. Work with copies on a separate recovery host/directory.

Expected result: You know what recovery point and software version the backup represents.

If not: A database dump alone contains metadata, not photos/videos. Asset folders alone do not recreate Immich’s users and file-path records. Inventory what survives before starting.

Safe stop: Do not delete a surviving production database, run down -v, or point a rehearsal at production storage.

Recreate a compatible, isolated deployment

Check: Obtain the official release Compose file and use the backup’s matching Immich version first. Use fresh database storage, a separate Compose project/container names and a loopback-only or restricted test port. Keep mobile uploads, reverse proxy and automated jobs away from the rehearsal.

Expected result: The recovery stack cannot overwrite or receive traffic intended for the old instance.

If not: If the backup predates v2.5.0, use the official documentation version selector and its manual restore instructions. The backup/restore process changed in v2.5.0; do not mix arbitrary current CLI commands with an old dump.

Restore the filesystem at the paths the database expects

Check: Populate the new UPLOAD_LOCATION from the backup, retaining backups, encoded-video, library, profile, thumbs and upload directories where present. Recreate external-library mounts at the same container paths. Preserve ownership so the service can read/write its files.

Expected result: The restored paths and external mounts match the saved instance, and original photos/videos are present.

If not: Do not flatten nested directories or import old upload/library files as new mobile uploads. Generated thumbnails/encoded files can be rebuilt where supported, but originals cannot be recreated from the database.

Use the supported database restore for this version

Check: For the current UI flow, start the isolated services and choose Restore from backup on the welcome screen. Review storage integrity checks, choose the matching dump (or upload the .sql.gz through the supported selector), and confirm only on the recovery instance.

Expected result: The database restore and health check complete, and the recovered account can log in.

If not: On an existing instance the matching control is Administration → Maintenance → Restore database backup. This replaces its current database: take a fresh backup first and do not treat it as a harmless merge.

Safe stop: If version compatibility, folder checks or database restore fail, preserve logs and snapshots before retrying; do not reset surviving storage as a shortcut.

Verify originals and application metadata

Check: Compare users and asset totals with recorded backup evidence. Open representative old/new photos and videos, download originals, compare file hashes against the backup and check dates, albums, favourites, sharing and external libraries.

Expected result: Selected original downloads match the backup and required metadata/workflows are present.

If not: A login page or visible thumbnail is not enough. Missing originals usually require a mount/path/backup inventory investigation before regenerating derived content.

Cut over only after the rehearsal passes

Check: Retain a written recovery checklist, the tested version and backup timestamp. Keep the old backup intact, upgrade through the supported path separately, then deliberately route clients to the recovered instance and verify one new upload plus a fresh database/files backup.

Expected result: Existing library and new uploads both work; a new recoverable backup exists.

If not: Pause cutover when any sample original, account, library mount or restore check fails. Keep the old copies until an independent backup of the recovered system is verified.