Recovery Overview
This section provides step-by-step recovery procedures for common Beads issues. Each runbook follows a consistent format: Symptoms, Diagnosis, Solution (5 steps max), and Prevention.
Common Issues
| Issue | Symptoms | Runbook |
|---|---|---|
| Database Corruption | SQLite errors, missing data | Database Corruption |
| Merge Conflicts | Dolt conflicts during sync | Merge Conflicts |
| Circular Dependencies | Cycle detection errors | Circular Dependencies |
| Sync Failures | bd sync errors | Sync Failures |
Quick Diagnostic
Before diving into specific runbooks, try these quick checks:
# Check Beads status
bd status
# Verify Dolt server is running
bd doctor
# Check for blocked issues
bd blocked
tip
Most issues can be diagnosed with bd status. Start there before following specific runbooks.
Getting Help
If these runbooks don't resolve your issue:
- Check the FAQ
- Search existing issues
- Open a new issue with diagnostic output