Home Assistant History/Recorder Troubleshooting

Symptom: History page shows no data or is blank

Quick Diagnosis Flow

Check if recorder is running

curl -s -H "Authorization: Bearer $HA_TOKEN" \
  https://homeassistant.familie-schoen.com/api/services/recorder |
  jq '.[].service'

If recorder service is missing, the recorder integration may be disabled.

Check HA core logs for recorder errors
```
curl -s -H "Authorization: Bearer $HA_TOKEN" \
  https://homeassistant.familie-schoen.com/api/error_log
```
Look for: sqlite3.DatabaseError, database is locked, disk I/O error, Recorder thread encountered an error, purge failures.
Check disk space (via SSH or HA API)
- HA OS: ha os info or check Settings → System → Storage in UI
- Docker/container: df -h inside the container
- Recorder stops writing when partition is >95% full
Check database size
- SQLite default: /config/home-assistant_v2.db
- If >2GB on SQLite, consider switching to PostgreSQL or MySQL
- Large DB causes slow queries → history appears empty (timeout)

Check recorder config in configuration.yaml

recorder:
  purge_keep_days: 10
  db_url: sqlite:///config/home-assistant_v2.db
  include:
    domains:
      - sensor
      - switch
  exclude:
    domains:
      - automation

Overly restrictive include/exclude filters can hide entities from history.

Common Causes (ranked by frequency)

Cause	Fix
Recorder DB corrupt	Stop HA, delete `.db` + `.db-wal` + `.db-shm`, restart
Disk full	Free space, run `recorder.purge` service
Recorder stuck on purge	Call `recorder.disable` then `recorder.enable`
SQLite lock contention	Switch to external DB (MySQL/PostgreSQL)
`history:` integration disabled	Add `history:` to configuration.yaml
Too many entities recorded	Add `exclude` filters, reduce retention
Time zone mismatch	Check `time_zone:` in configuration.yaml

Useful API Endpoints

# Get states for an entity (last 24h)
GET /api/history/period/{timestamp}?filter_entity_id=sensor.xxx

# Get all entity states now
GET /api/states

# Error logs
GET /api/error_log

# Call service
POST /api/services/recorder/purge
POST /api/services/recorder/disable
POST /api/services/recorder/enable

# HA config check
GET /api/config/core/check_config

SSH Access

HA is VM 106 on proxmox1 (10.0.20.10). Access via Proxmox guest agent:

ssh -i ~/.ssh/id_ed25519_proxmox root@10.0.20.10 \
  "qm guest exec 106 --timeout 30 -- bash -c 'docker logs homeassistant 2>&1 | tail -30'"

Config file: /mnt/data/supervisor/homeassistant/configuration.yaml (inside VM).

External Database (MariaDB Galera + MaxScale)

Production HA uses MariaDB Galera cluster (3 nodes) behind MaxScale VIP, NOT SQLite. If recorder errors mention MySQL/MariaDB (MySQLdb.OperationalError), see: references/galera-cluster-recovery.md for full cluster recovery procedure.

Quick checks:

# MaxScale server states
ssh -i ~/.ssh/id_ed25519_proxmox debian@10.0.30.81 "maxctrl list servers"

# Direct DB connection test via MaxScale
ssh -i ~/.ssh/id_ed25519_proxmox debian@10.0.30.81 \
  "mariadb -h 127.0.0.1 -P 3306 -u ha_recorder -p'<password>' --skip-ssl -e \"SELECT 1\""

# Galera node status
ssh -i ~/.ssh/id_ed25519_proxmox debian@10.0.30.71 \
  "sudo mariadb -e \"SHOW GLOBAL STATUS LIKE 'wsrep_cluster_size'; SHOW GLOBAL STATUS LIKE 'wsrep_local_state_comment';\""

Common Galera failure symptoms:

All nodes failed since same timestamp → simultaneous crash (network or power)
Access denied from HA → MaxScale can't route to any backend
Lost connection during query → MaxScale routed to Donor/Desynced node without available_when_donor=true

Recovery Procedure (corrupt SQLite DB)

# Via SSH to HA
ha core stop
mv /config/home-assistant_v2.db /config/home-assistant_v2.db.bak
rm -f /config/home-assistant_v2.db-wal /config/home-assistant_v2.db-shm
ha core start

History will rebuild from scratch. Old history is lost (backup exists as .bak).

Prevention

Set recorder.commit_interval: 1 (flush more frequently, smaller WAL)
Add exclude filters for noisy domains (automation, script, timer)
Consider external DB for installations with 500+ entities
Monitor disk space with a sensor/alert

4.4 KiB Raw Blame History