How to Repair Immich After Its Database Volume Fills Up
When the Immich database volume fills, stop new Immich writes, preserve the PostgreSQL data directory, and create safe working space before attempting recovery. Do not delete files from pg_wal or other PostgreSQL internals simply because they are large.
A full database filesystem can interrupt checkpoints or crash recovery, so repeated restarts may keep failing even after the photo application itself looks healthy. First prove which filesystem is fullโPostgreSQL data, Docker root storage, shared memory, or another mountโthen recover that layer without destroying the evidence you may need for rollback.
Confirm Which Filesystem Is Full and Stop Further Writes
Check byte and inode availability for the PostgreSQL mount, Docker data root, host root filesystem, and any tmpfs/shared-memory path named in the error. Match the timestamp to PostgreSQL logs. A โno space left on deviceโ message from pg_wal means something different from a full image cache or thumbnail partition.
An Immich database recovery discussion shows PostgreSQL aborting recovery because it could not write a temporary WAL file after storage filled. The case is old and deployment-specific, but it demonstrates why changing file permissions or restarting the stack does not repair a capacity failure.
Pause uploads and background jobs, then stop the application components that generate new database work. Preserve the first failing log window and the mount map. If the full filesystem is not actually the PostgreSQL data filesystem, repair the real location rather than moving the database unnecessarily.
Preserve PostgreSQL State Before Making Room
With PostgreSQL stopped, take a filesystem snapshot or complete copy of the database data directory when storage and tooling allow it. Include the WAL directory and any non-default tablespaces as one state. This safety copy lets you return to the incident point if the next recovery attempt makes the situation worse.
The PostgreSQL out-of-disk recovery guidance makes the critical rule explicit: WAL is part of database consistency, not ordinary log clutter, and manually deleting it can corrupt the database. Create capacity by expanding/moving the volume or removing unrelated safe data instead. Do not immediately overwrite the failed database with the last backup unless you have decided the current state is unrecoverable and accept losing changes since that backup. Preserving the filled instance gives you both a rollback point and evidence for why the capacity disappeared.
Recover PostgreSQL First, Then Decide Whether Immich Needs Repair
Once adequate space exists, start PostgreSQL by itself or with the minimum required stack and watch recovery logs. A clean startup, successful health check, and normal read access are stronger signals than a container status of โrunning.โ Take a fresh database-native backup as soon as the database is stable enough to do so.
The ZimaSpace guide to Immich database maintenance versus replacement provides the next boundary: ordinary size or performance problems should not trigger a rebuild, while repeatable integrity or recovery failure may justify restoring a verified database copy.
Start Immich only after PostgreSQL remains healthy.
Check users, timeline, several originals, albums, search, and one controlled new upload. If the database starts but application queries fail consistently, preserve the new logs and determine whether schema/version compatibility or data integrityโnot free spaceโis now the active problem.
Fix the Growth Cause and Prove the System Can Fill Safely Again
Measure which part grew: normal database tables, WAL retention, backups stored on the same volume, logs, Docker layers, or an unexpected path. If the incident came from a failed archive/replication workflow or another service writing into the database volume, repair that cause rather than merely increasing capacity.
Set alerts well before the volume reaches the point where PostgreSQL cannot checkpoint or recover. Monitor both percentage and absolute free space because a large volume can have a small percentage free yet still enough working room, while a tiny database volume can become dangerous quickly. Keep database backups off the same failure boundary they protect.
Finally repeat a normal upload and background-processing cycle, create a fresh database backup, restart the stack, and reboot the host. A pass has stable free-space decline, no WAL/recovery errors, readable old and new assets, and a documented threshold that triggers action before writes fail again.
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.
Why Does Immich Recreate Missing Files With the Wrong Owner?
Immich should not silently recreate missing source originals. Identify the regenerated file type and writer, then fix the creation identity.
