Database Corruption Recovery

This runbook helps you recover from SQLite database corruption in Beads.

Symptoms

• SQLite error messages during bd commands
• "database is locked" errors that persist
• Missing issues that should exist
• Inconsistent state between JSONL and database

Diagnosis

# Check database integrity
bd status

# Look for corruption indicators
ls -la .beads/beads.db*

If you see -wal or -shm files alongside beads.db, a transaction may have been interrupted.

Solution

warning

Back up your .beads/ directory before proceeding.

Step 1: Stop the daemon

bd daemon stop

Step 2: Back up current state

cp -r .beads .beads.backup

Step 3: Rebuild from JSONL (source of truth)

bd doctor --fix

Step 4: Verify recovery

bd status
bd list

Step 5: Restart daemon

bd daemon start

Prevention

• Avoid interrupting bd sync operations
• Let the daemon handle synchronization
• Use bd daemon stop before system shutdown