Interactive Troubleshooter

Published: Sep 17, 2026

Home Assistant Database Corrupted After Power Loss: Recovery Guide

Time: 15 mins Level: Beginner

By StepDiag Engineering Team

Reviewed by Ibraheem Taofeeq Opeyemi

Sudden power outages frequently corrupt Home Assistant's default SQLite recorder database (home-assistant_v2.db) due to unwritten Write-Ahead Logging (WAL) frames or incomplete B-tree page writes. This diagnostic decision tree isolates database format failures, provides data recovery extraction pipelines, and covers system fixes for SQLite and MariaDB engine locks.

Full Diagnostic Tree & Step-by-Step Overview

What error or behavior is Home Assistant showing following the power restoration?

Core log displays 'sqlite3.DatabaseError: database disk image is malformed' for default home-assistant_v2.db
External MariaDB/MySQL add-on fails to start with 'InnoDB: Corruption in header' or table crashed errors
Home Assistant boots into Safe Mode or loops on 'Starting Recorder' integration initialization
Database is accessible, but history graphs fail to render and logbook displays 'database is locked'

What specific SQLite file state or integrity check result is returned for home-assistant_v2.db?

PRAGMA integrity_check returns 'Error: database disk image is malformed' with broken B-Tree pages
Main DB is intact, but home-assistant_v2.db-wal (Write-Ahead Log) is corrupted or oversized
Home Assistant attempts automatic purge on startup but crashes due to disk space exhaustion
Storage corruption is catastrophic and sqlite3 CLI dump command fails completely

Recover Malformed SQLite Database Using SQL Dump and Rebuild Pipeline

Solution:

Root Cause: Unwritten Page Cache and B-Tree Structure Corruption

When power cuts during active write transactions, SQLite's memory cache page fails to flush to physical storage. This results in missing header pointers or invalid page counts within home-assistant_v2.db, causing the Python sqlite3 driver to throw database disk image is malformed during read operations.

# Diagnostic Verification:

Access the Home Assistant Terminal (SSH or Advanced Web Terminal) and execute a diagnostic integrity check on the database file:

bash organize
cd /config
sqlite3 home-assistant_v2.db "PRAGMA integrity_check;"

If output shows error lines such as Page N is never used or malformed, the B-Tree structure is corrupted.

# Step-by-Step Fix:

1. Stop the Home Assistant Core service to release file locks:

bash
   ha core stop

2. Navigate to the configuration directory and back up the malformed database files:

bash
   cd /config
   mv home-assistant_v2.db home-assistant_v2.db.corrupt
   mv home-assistant_v2.db-wal home-assistant_v2.db-wal.bak 2>/dev/null || true

3. Dump the uncorrupted schema and records from the corrupted file into a clean database:

bash
   sqlite3 home-assistant_v2.db.corrupt ".mode insert" ".dump" | sqlite3 home-assistant_v2.db.recovered

4. Replace the old database with the recovered database file and set correct file permissions:

bash
   mv home-assistant_v2.db.recovered home-assistant_v2.db
   chmod 664 home-assistant_v2.db

5. Start Home Assistant Core:

bash
   ha core start

# Prevention & Long-Term Monitoring:

Connect the Home Assistant host system to an Uninterruptible Power Supply (UPS) integrated with the NUT (Network UPS Tools) integration for automated graceful shutdowns.

Flush Orphaned Write-Ahead Log (WAL) and Shared Memory Files

Solution:

Root Cause: Orphaned WAL Journal State Mismatch

SQLite operates in Write-Ahead Logging mode (PRAGMA journal_mode=WAL), creating home-assistant_v2.db-wal and home-assistant_v2.db-shm. An abrupt power cut leaves raw uncommitted transactions in the WAL file without matching checkpoint headers in the main DB, triggering startup crashes.

# Diagnostic Verification:

Check directory contents and file sizes in /config:

bash
ls -lh /config/home-assistant_v2.db*

If home-assistant_v2.db-wal is significantly larger than home-assistant_v2.db or integrity check passes on the main DB file when isolated, the WAL checkpoint process is desynchronized.

# Step-by-Step Fix:

1. Stop Home Assistant Core:

bash
   ha core stop

2. Force a manual SQLite checkpoint to merge valid WAL frames into the primary file:

bash
   cd /config
   sqlite3 home-assistant_v2.db "PRAGMA wal_checkpoint(TRUNCATE);"

3. If the command returns SQLITE_CORRUPT, back up and remove the journal and shared memory helper files:

bash
   rm -f home-assistant_v2.db-shm home-assistant_v2.db-wal

4. Start Home Assistant Core to auto-generate clean WAL runtime files:

bash
   ha core start

# Prevention & Long-Term Monitoring:

Ensure storage media (e.g., microSD or SSD) supports active write-caching flushing during hardware power state changes.

Clear Disk Space Locks and Purge Historic Recorder Data

Solution:

Root Cause: Storage Exhaustion During Automated Database Repair

Upon detecting database corruption, Home Assistant's recorder component attempts to re-index or move corrupted files. If storage space is full (>95% usage), SQLite cannot write temporary rollback journals (eta-*), freezing the entire operating system in a boot loop.

# Diagnostic Verification:

Verify available storage space on the Home Assistant root filesystem:

bash
df -h /config

If available space is under 1 GB, disk space exhaustion is preventing SQLite recovery processes from executing.

# Step-by-Step Fix:

1. Stop Home Assistant Core:

bash
   ha core stop

2. Remove old core backup archives or temporary files to free up space:

bash
   rm -f /backup/*.tar

3. Truncate states and events from the SQLite database using low-overhead deletion commands:

bash
   sqlite3 /config/home-assistant_v2.db "DELETE FROM states WHERE created_ts < strftime('%s', 'now', '-3 days');"
   sqlite3 /config/home-assistant_v2.db "VACUUM;"

4. Restart Home Assistant Core:

bash
   ha core start

# Prevention & Long-Term Monitoring:

Configure db_max_retention in configuration.yaml under recorder: to keep data history within reasonable limits (e.g., 7–10 days).

Perform Complete Database Reset and Schema Initialization

Solution:

Root Cause: Severe Storage Sector Corruption or Unrecoverable Headers

If power cuts occur during intense flash storage block erase cycles, physical blocks on SD cards or low-end SSDs can corrupt header offset blocks, making the file entirely unreadable by sqlite3 CLI tools.

# Diagnostic Verification:

Run sqlite3 /config/home-assistant_v2.db ".schema". If output returns Error: file is not a database or file is encrypted or is not a database, the database header is completely destroyed.

# Step-by-Step Fix:

1. Stop Home Assistant Core:

bash
   ha core stop

2. Move corrupted database files to a backup archive directory:

bash
   mkdir /config/db_corrupt_archive
   mv /config/home-assistant_v2.db* /config/db_corrupt_archive/

3. Start Home Assistant Core. The recorder integration will automatically detect the missing database and generate a brand-new, clean home-assistant_v2.db file with modern schema definitions:

bash
   ha core start

4. Verify that the new database file is created successfully:

bash
   ls -la /config/home-assistant_v2.db

# Prevention & Long-Term Monitoring:

Replace microSD storage with industrial-grade High Endurance SD cards or external USB-NVMe SSD drives to prevent storage degradation.

What error condition is reported by MariaDB / MySQL container logs?

InnoDB storage engine fails to start with 'InnoDB: Page space ID != record space ID'
MariaDB crashes continuously due to corrupted aria log files (aria_log.00000001)
MariaDB process runs, but recorder throws 'Table homeassistant.states is marked as crashed'
Add-on fails to start due to lock file locks (aria_log_control / ibdata1 lock)

Force InnoDB Recovery in MariaDB Add-On Configuration

Solution:

Root Cause: InnoDB Tablespace Header Corruption

Unexpected system resets during InnoDB write cycles cause severe doublewrite buffer mismatches in ibdata1 or individual .ibd table files. MariaDB refuses to start in standard mode to prevent spreading data corruption.

# Diagnostic Verification:

Inspect the MariaDB add-on log output via Home Assistant UI (Settings > Add-ons > MariaDB > Logs):

text
[ERROR] InnoDB: Plugin initialization aborted with error Data structure corruption
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.

# Step-by-Step Fix:

1. Open the MariaDB add-on configuration tab or edit /config/mariadb/my.cnf via SSH.
2. Add the innodb_force_recovery directive under the [mysqld] section:

ini
   [mysqld]
   innodb_force_recovery = 4

3. Restart the MariaDB add-on. Mode 4 forces MariaDB to start in read-only mode, bypassing corrupted page checks.
4. Dump the data using mysqldump in terminal:

bash
   mysqldump -u homeassistant -p homeassistant > /config/mariadb_dump.sql

5. Stop MariaDB, remove innodb_force_recovery from my.cnf, delete corrupted data directories (/data/mariadb/*), restart the container, and restore the dump:

bash
   mysql -u homeassistant -p homeassistant < /config/mariadb_dump.sql

# Prevention & Long-Term Monitoring:

Ensure MariaDB log writes use transaction-safe commit settings (innodb_flush_log_at_trx_commit = 2).

Repair Corrupted Aria Control Logs in MariaDB Container

Solution:

Root Cause: Aria Storage Engine Log Sequence Corruption

MariaDB uses the Aria engine for internal temporary tables and system schema storage. Power failure corrupts active aria_log.00000001 log sequence files, preventing the MySQL daemon (mysqld) from completing initialization.

# Diagnostic Verification:

Check MariaDB add-on log entries for Aria initialization failures:

text
[ERROR] aria_chk: error: Pagepack error at page...
[ERROR] Plugin 'Aria' init function returned error.

# Step-by-Step Fix:

1. Stop the MariaDB add-on via Home Assistant CLI or UI:

bash
   ha addons stop core_mariadb

2. Access the host terminal or Docker container storage path for MariaDB (/usr/share/hassio/addons/data/core_mariadb/mariadb or /addon_config/mariadb).
3. Repair Aria control tables manually using aria_chk:

bash
   cd /addon_config/mariadb
   aria_chk --repair --force */*.MAI

4. Delete corrupted transactional Aria logs:

bash
   rm -f aria_log.*

5. Restart the MariaDB add-on:

bash
   ha addons start core_mariadb

# Prevention & Long-Term Monitoring:

Avoid placing external database directories on network-attached storage (NFS/SMB) prone to transient network cuts during outages.

Execute Automatic REPAIR TABLE Diagnostics on Crashed MariaDB Tables

Solution:

Root Cause: Unclosed MyISAM / Aria Table Indexes

If specific event tables are mid-write when power drops, table index headers are marked as 'crashed' or 'open'. While data remains intact, read queries fail until indexes are re-calculated.

# Diagnostic Verification:

Home Assistant core logs show database query exceptions:

text
sqlalchemy.exc.OperationalError: (mariadb.OperationalError) Table './homeassistant/states' is marked as crashed and should be repaired

# Step-by-Step Fix:

1. Access the MariaDB container shell or SSH terminal:

bash
   mysql -u homeassistant -p homeassistant

2. Run the CHECK TABLE command on recorder tables:

sql
   CHECK TABLE states, events, state_attributes, event_data;

3. Execute REPAIR TABLE on any table returning Corrupted or Crashed status:

sql
   REPAIR TABLE states;
   REPAIR TABLE events;
   REPAIR TABLE state_attributes;

4. Alternatively, execute mysqlcheck from the CLI shell:

bash
   mysqlcheck -u homeassistant -p --auto-repair --check homeassistant

# Prevention & Long-Term Monitoring:

Convert legacy MyISAM storage tables to transactional InnoDB engine formats.

Clear Stale MariaDB PID and Lock Files

Solution:

Root Cause: Stale Process ID (PID) File Lock Traps

During power failure, the MariaDB process is terminated without firing shutdown hooks that clear /var/run/mysqld/mysqld.pid and socket locks. Upon reboot, startup scripts detect active PID locks and abort initialization.

# Diagnostic Verification:

Add-on logs display:

text
[ERROR] Can't start server : Bind on unix socket: Address already in use
[ERROR] Another MySQL daemon already runs with the same socket.

# Step-by-Step Fix:

1. Stop the MariaDB add-on:

bash
   ha addons stop core_mariadb

2. Locate and purge stale lock files in the database data folder:

bash
   cd /addon_config/mariadb
   rm -f mysqld.pid ib_logfile*

3. Restart the MariaDB add-on:

bash
   ha addons start core_mariadb

# Prevention & Long-Term Monitoring:

Verify that the container runtime has proper clean-up privileges on system boot.

What specific initialization error causes the Home Assistant Recorder to stall?

Recorder component throws 'Schema Migration Failed' during startup migration
Home Assistant drops into Safe Mode citing 'Failed to initialize recorder'
Database is intact, but YAML recorder configuration contains invalid database URI paths
Recorder thread hangs indefinitely during startup due to I/O hardware read timeouts

Fix Interrupted Home Assistant Database Schema Migrations

Solution:

Root Cause: Schema Migration Inconsistency

If power is cut while Home Assistant is executing a database schema version upgrade, the schema_changes table records an incomplete migration state. Subsequent core boots attempt to re-apply structural SQL migrations on partially modified tables, triggering fatal schema errors.

# Diagnostic Verification:

Check /config/home-assistant.log for migration failures:

text
[homeassistant.components.recorder.migration] Database migration failed: Duplicate column name

# Step-by-Step Fix:

1. Stop Home Assistant Core:

bash
   ha core stop

2. Open the SQLite database CLI:

bash
   sqlite3 /config/home-assistant_v2.db

3. Inspect the active schema version table:

sql
   SELECT * FROM schema_changes;

4. If the latest migration row lacks a completion state, update the schema version manually to match the current target schema or delete the stalled migration record:

sql
   DELETE FROM schema_changes WHERE change_id IS NULL;
   .exit

5. Restart Home Assistant Core:

bash
   ha core start

# Prevention & Long-Term Monitoring:

Never power off or restart Home Assistant host hardware while a Core version update is in progress.

Reset Home Assistant Recorder Integration and Move Stale Database

Solution:

Root Cause: Unhandled Recorder Integration Initialization Crash

When the recorder integration encounters unexpected file system errors during startup validation, it raises an unhandled exception. Home Assistant halts core startup to protect configuration state and drops into Safe Mode.

# Diagnostic Verification:

Home Assistant notification tray shows Safe Mode Activated with log entry:

text
Setup failed for recorder: Integration failed to initialize.

# Step-by-Step Fix:

1. Access terminal via SSH or Samba share.
2. Rename home-assistant_v2.db to isolate the broken recorder instance:

bash
   mv /config/home-assistant_v2.db /config/home-assistant_v2.db.old

3. Reboot Home Assistant via CLI:

bash
   ha host reboot

4. Home Assistant will start normally and re-create a clean database file.

# Prevention & Long-Term Monitoring:

Refer to Home Assistant Documentation for recorder architecture recommendations.

Correct Database Connection URI and Auth Strings in configuration.yaml

Solution:

Root Cause: Malformed db_url Protocol Syntax

Following unexpected crashes, configuration restores or fallback YAML changes may corrupt the db_url database connection string under the recorder: section in configuration.yaml.

# Diagnostic Verification:

Check Home Assistant logs for connection setup errors:

text
ValueError: Could not parse rfc1738 URL from string 'db_url'

# Step-by-Step Fix:

1. Open /config/configuration.yaml using File Editor or VS Code add-on.
2. Verify recorder: configuration block and correct protocol formatting:

yaml
   recorder:
     db_url: mysql://homeassistant:YOUR_PASSWORD@core-mariadb/homeassistant?charset=utf8mb4

*(For default SQLite, remove the db_url line completely).*
3. Validate YAML syntax using CLI:

bash
   ha core check

4. Restart Home Assistant Core:

bash
   ha core rebuild

# Prevention & Long-Term Monitoring:

Use Home Assistant Secrets (secrets.yaml) to manage database credentials and prevent syntax typos during edits.

Resolve Host I/O Storage Latency and Hardware Block Locks

Solution:

Root Cause: Flash Storage Controller Write Lockout

When power failure impacts flash memory controllers (e.g., cheap SD cards or degraded USB drives), the storage medium locks into Read-Only mode to protect flash cells. SQLite write operations hang indefinitely waiting for I/O ACK signals.

# Diagnostic Verification:

Execute a write test on the filesystem using terminal:

bash
touch /config/test_write.txt

If terminal returns Read-only file system or command hangs indefinitely, hardware storage failure has occurred.

# Step-by-Step Fix:

1. Shut down the system safely and remove storage media.
2. Insert the card/drive into another Linux system and inspect dmesg output:

bash
   dmesg | grep -i "I/O error"

3. Run filesystem repair (fsck) on host partitions:

bash
   fsck.ext4 -y /dev/sdX2

4. If the drive remains in read-only hardware lock, restore a recent Home Assistant backup onto a new storage drive.

# Prevention & Long-Term Monitoring:

Utilize Home Assistant Google Drive Backup or Nabu Casa Cloud Backups for automated off-site backup storage.

What performance or operational issue is occurring on the functioning database?

Logbook displays 'database is locked' errors during concurrent entity writes
History card loading fails with 'SQLite busy timeout' during purge operations
Database size inflates rapidly (>10GB) due to unindexed auto-commit state tracking
Corrupted entity attributes cause specific UI history rendering crashes

Optimize SQLite Busy Timeout and Write-Ahead Log Concurrency Settings

Solution:

Root Cause: Database File Locking Contention

High-frequency event writes (e.g., energy sensors, power meters) lock the SQLite database file during transaction commits. If write locks exceed the default 30-second timeout, subsequent UI queries fail with database is locked.

# Diagnostic Verification:

Review core logs for concurrency lockouts:

text
sqlite3.OperationalError: database is locked

# Step-by-Step Fix:

1. Open /config/configuration.yaml.
2. Add execution timeout overrides and filter out chatty entities from the recorder:

yaml
   recorder:
     auto_purge: true
     commit_interval: 10
     exclude:
       domains:
         - updater
       entity_globs:
         - sensor.power_*

3. Apply WAL mode manually via SQLite CLI if it was reset during crash recovery:

bash
   sqlite3 /config/home-assistant_v2.db "PRAGMA journal_mode=WAL;"

4. Restart Home Assistant Core.

# Prevention & Long-Term Monitoring:

Set commit_interval to 10 or 15 seconds to batch write transactions and reduce I/O pressure on storage.

Perform Manual Database Re-Index and Vacuuming

Solution:

Root Cause: Database Fragmentation and B-Tree Index Bloat

Abrupt interruptions leave orphaned indexes and un-cleared pages inside home-assistant_v2.db. SQLite query execution plans degrade, causing simple history lookup requests to time out.

# Diagnostic Verification:

Measure query execution speed in sqlite3 CLI:

bash
time sqlite3 /config/home-assistant_v2.db "SELECT COUNT(*) FROM states;"

If timing exceeds 5–10 seconds on medium-sized databases, re-indexing is required.

# Step-by-Step Fix:

1. Stop Home Assistant Core:

bash
   ha core stop

2. Rebuild database indexes and reclaim unused disk space:

bash
   sqlite3 /config/home-assistant_v2.db "REINDEX;"
   sqlite3 /config/home-assistant_v2.db "VACUUM;"

3. Restart Home Assistant Core:

bash
   ha core start

# Prevention & Long-Term Monitoring:

Run Home Assistant's built-in recorder.purge service with repack: true periodically via an automated Home Assistant automation.

Purge Unfiltered High-Frequency Entities from Database

Solution:

Root Cause: Unfiltered State Attribute Tracking Bloat

Power failures can break automated purge cron jobs. Without regular purging, high-frequency state updates (such as CPU monitors or fast-polling Zigbee power plugs) create millions of DB rows within days.

# Diagnostic Verification:

Identify top space-consuming tables inside the SQLite database:

bash
sqlite3 /config/home-assistant_v2.db "SELECT name, pgsize * count / 1024 / 1024 AS size_mb FROM dbstat GROUP BY name ORDER BY size_mb DESC LIMIT 5;"

# Step-by-Step Fix:

1. Trigger a forced manual purge via Home Assistant Developer Tools or CLI service call:

bash
   ha service call recorder.purge --data '{"keep_days":2,"repack":true}'

2. Update configuration.yaml to exclude non-essential high-frequency entities from being recorded:

yaml
   recorder:
     purge_keep_days: 7
     exclude:
       entity_globs:
         - sensor.processor_use*

# Prevention & Long-Term Monitoring:

Use targeted integrations like InfluxDB or Prometheus for long-term historical metrics, keeping Home Assistant's internal database lean.

Clean Corrupted JSON State Attributes from Database Records

Solution:

Root Cause: Malformed JSON String Ingestion in State Attributes

Incomplete writes during power interruptions can write malformed JSON strings into the shared_attrs or state_attributes table. When the frontend attempts to parse these strings to render history graphs, the JavaScript engine crashes.

# Diagnostic Verification:

Check Home Assistant core log for JSON decode errors originating from recorder fetches:

text
json.decoder.JSONDecodeError: Unterminated string starting at: line 1 column 1234 (char 1233)

# Step-by-Step Fix:

1. Stop Home Assistant Core:

bash
   ha core stop

2. Purge recent state attributes that failed JSON formatting checks:

bash
   sqlite3 /config/home-assistant_v2.db "DELETE FROM state_attributes WHERE attributes NOT LIKE '{%';"

3. Restart Home Assistant Core:

bash
   ha core start

# Prevention & Long-Term Monitoring:

Ensure all custom integration components installed via HACS parse input strings through safe JSON validators.

Related Diagnostic Guides

Notion Offline Mode Data Lost: Version History & Cache Recovery Guide

Excel File Crashes on Open: Safe Mode and Add-ins Recovery Guide

Google Calendar Not Syncing to Outlook: Complete Fix Guide

Slack Notifications Delayed on Android 15: Deep Diagnostics & Fixes

PDF Won't Print: Font Embedding and Driver Fix Guide

Subscribe to StepDiag

Embed Guide on Your Website