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 |
|---|
| Init Safety Refusals | bd init or bd dolt refuses with a pattern code like pk-fork-refused | Recovery Playbooks |
| Database Corruption | Database errors, missing data | Database Corruption |
| Merge Conflicts | Dolt conflicts during sync | Merge Conflicts |
| Circular Dependencies | Cycle detection errors | Circular Dependencies |
| Sync Failures | bd dolt push/bd dolt pull errors | Sync Failures |
| Removing beads | Uninstall bd or strip beads from a repo | Uninstalling |
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
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
