# Home Assistant History/Recorder Troubleshooting

## Symptom: History page shows no data or is blank

### Quick Diagnosis Flow

1. **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.

2. **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.

3. **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

4. **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)

5. **Check recorder config in configuration.yaml**
   ```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:
```bash
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:
```bash
# 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)

```bash
# 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