How to Prevent Immich Backups From Capturing Inconsistent State
Prevent inconsistent Immich backups by treating the database and media as one recovery unit whose capture order and write activity are deliberately controlled.
A backup can contain every file it was asked to copy and still restore badly if the database references assets that were not captured, or the media copy contains a different point in time from the catalog. Define the consistency boundary first, choose a stopped or coordinated live method, and validate the result in isolation.
Define the Recovery Unit Before Scheduling the Backup
List the PostgreSQL database, uploaded media, profile data, deployment configuration, environment values, secrets, and any custom storage paths required to recreate the service. Mark generated thumbnails, encoded videos, and model files separately according to whether your recovery policy protects or regenerates them.
The ZimaSpace comparison of live and stopped Immich backups explains the basic consistency choice. This prevention workflow goes one step further: whichever method you choose must produce a documented point that can be restored without guessing which database belongs to which media copy.
Write the restore order beside the backup scope. If the plan says “restore photos” but does not say which database dump, configuration, credentials, and storage mappings reconnect those photos to users and albums, the backup definition is incomplete before the first scheduled run begins.
Use a Stopped Capture When the Simplest Boundary Is Acceptable
For a small household that can tolerate a short maintenance window, pause uploads and stop the application services that write library state. Create the database backup, capture the media and configuration, then restart only after the snapshot or copy has a clear timestamp and completion result.
A stopped application does not automatically make a bad path correct. Verify that the database export succeeded, the intended media roots were included, and the backup destination is independent of the live data it is meant to recover. Record the start and end times so later restores can identify the exact generation.
The method passes when no application writes occur during capture and a test restore returns the expected users, asset counts, albums, and sampled originals. If downtime regularly exceeds the household tolerance, move to a coordinated live method rather than quietly letting uploads resume halfway through a file copy.
For Live Backups, Capture the Database and Files in a Known Order
When Immich must remain available, create a database-native consistent dump rather than copying the active PostgreSQL data directory as ordinary files. Then capture or snapshot the media tree in the documented order while tracking uploads that arrive during the backup window.
The hands-on Immich database backup workflow demonstrates the database-aware approach. Commands and container names can vary by deployment, so the transferable principle is to ask PostgreSQL for a consistent backup instead of trusting a live recursive copy of database files.
Prefer an order that cannot leave the restored database pointing at media that never entered the backup. If the filesystem copy contains extra files that the database does not yet know about, those can be reconciled more safely than database records whose referenced originals are absent. Document any uploads that cross the boundary.
Coordinate Filesystem Snapshots With Database Hooks Instead of Assuming Atomicity
Filesystem snapshots are valuable because they capture a volume quickly, but they do not make two independently changing systems transactionally consistent by themselves. If database and media live on different datasets or devices, define pre-snapshot and post-snapshot hooks and keep their timing visible in the backup log.
A 2026 example combining backup software with Btrfs snapshot hooks shows why snapshot orchestration needs explicit application or database boundaries. Use the idea to coordinate captures; do not copy its filesystem commands blindly onto a different layout.
If the snapshot tool cannot coordinate the database and media time boundary, fall back to a logical database dump plus media backup instead of claiming atomic recovery. Complexity is justified only when the restore drill proves that the faster capture still returns coherent application state.
Make Restore Testing Part of the Backup Schedule
A successful backup job is only evidence that capture completed. Select a recent generation periodically, restore it under an isolated hostname, attach the expected storage, and verify users, representative originals, albums, permissions, search behavior, and a fresh database backup from the restored instance.
The PostgreSQL recovery overview from PostgreSQL backup and restore planning emphasizes restore validation and recovery objectives rather than treating dump creation as the finish line. Apply the same discipline to the combined Immich recovery unit.
Fail the backup policy if the database restore succeeds but files are missing, if media opens without users or relationships, or if recovery depends on a secret stored only on the failed host. Fix scope, ordering, retention, or independence before increasing backup frequency; more inconsistent copies do not create a reliable recovery point.
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.
