Recovery Overview - Beads Documentation

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
History Bloat	Store grows unbounded; `dolt gc` reclaims nothing	History Bloat
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