How to Repair Home Assistant After Its Database Volume Fills Up

When the Home Assistant database volume is full, stop new writes first. Create working space without deleting the active database, preserve a copy, and determine whether Recorder can open and maintain the database before choosing purge, repair, or restore.

A full volume can block the very cleanup operation intended to fix it, especially when repack or database reconstruction needs temporary space. Keep the order conservative: stop Home Assistant, prove which filesystem is full, move unrelated files or expand the volume, copy the database, check logs and integrity, then apply the least destructive recovery that matches the result.

Stop Writes and Confirm the Actual Full Filesystem

Stop Home Assistant or Recorder as soon as database write failures repeat. Confirm the filesystem, mount, or thin volume that contains the active database and compare total space, free space, inodes, database size, logs, backups, and container writable layers. A full system disk and a full external database volume require different fixes.

Do not assume the database is the only consumer. Old backups, debug logs, exports, snapshots, and unrelated container layers may provide safer emergency space. Move or delete only files whose purpose and backup status are known; do not remove the active database, WAL, journal, or database-engine files individually.

The ZimaSpace guide on finding Docker disk use outside mapped data is the right parallel check when the configured database path looks small but the host system disk is still exhausted.

Create Working Space and Preserve the Database

Prefer expanding the volume or moving unrelated archives to another verified disk. If that is impossible, copy the stopped database and its related files to storage with enough capacity before attempting maintenance. Record ownership, permissions, engine, Home Assistant version, and database URL.

Repack is not an emergency first step on a full filesystem because it can require substantial temporary space. Community troubleshooting notes that SQLite repack may need free space comparable to the database size; the practical point is to create working space before repack rather than trust a nearly full volume.

After making space, confirm the filesystem is writable and stable. If it remounted read-only, reports hardware errors, or immediately loses space again, stop and repair the storage layer before opening the database.

Choose Purge, Integrity Repair, or Known-Good Restore

Start Home Assistant only long enough to inspect Recorder logs and database status. If the database opens cleanly, reduce retention or exclude noisy entities and run a purge without repack first. This lowers logical data volume while avoiding the largest temporary-space step.

If integrity errors appear, stop writes again and work on a copy. Use the database engine's supported integrity and recovery tools, or restore a known-good backup. Do not repeatedly start Home Assistant against a damaged database, because new writes can complicate recovery and obscure the original failure.

If no usable database copy or backup exists, creating a new Recorder database restores operation but loses history. Treat that as the last recovery branch, preserve the failed database for later analysis, and keep configuration and registries separate from the history decision.

Featured

ZimaCube 2 Personal Cloud Home NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

Reduce the Growth Source Before Returning to Service

Identify what filled the volume: excessive entity updates, long retention, large logs, backup accumulation, failed purge, database bloat, or a volume smaller than intended. Fix the measured source rather than applying every cleanup option at once.

Set a defensible retention period, exclude entities whose high-frequency history has little value, return logging from debug to normal, move backup copies off-host, and alert on both free space and growth rate. Leave working room for upgrades, backups, schema changes, and maintenance.

Compare the recovered database with the ZimaSpace criteria for database maintenance versus replacement when repeated corruption or integrity failures make continued repair less trustworthy than a known-good restore.

Validate Recovery Under Recorder Load

Start Home Assistant and confirm current states, new history writes, logbook queries, automation actions, and database size. Run the same high-update workload that preceded the failure while watching free space, write errors, database latency, and growth rate.

Restart Home Assistant twice and run the next scheduled purge or backup. Recovery passes only if the database reopens, history advances, free space remains above the stop boundary, and no integrity or read-only errors return.

Roll back to the preserved copy or known-good backup if maintenance creates new corruption, history disappears unexpectedly, or the volume begins filling at the same rate. Escalate storage faults, database-engine errors, and reproducible Recorder failures with logs and the preserved timeline.