ContextQMD
Back to Beads

Recovery Overview

docs/recovery/index.md

1.2.11.5 KB
Original Source

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

IssueSymptomsRunbook
Init Safety Refusalsbd init or bd dolt refuses with a pattern code like pk-fork-refusedRecovery Playbooks
Database CorruptionDatabase errors, missing dataDatabase Corruption
Merge ConflictsDolt conflicts during syncMerge Conflicts
Circular DependenciesCycle detection errorsCircular Dependencies
Sync Failuresbd dolt push/bd dolt pull errorsSync Failures
History BloatStore grows unbounded; dolt gc reclaims nothingHistory Bloat
Removing beadsUninstall bd or strip beads from a repoUninstalling

Quick Diagnostic

Before diving into specific runbooks, try these quick checks:

bash
# 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. </Tip>

Getting Help

If these runbooks don't resolve your issue:

  1. Check the FAQ
  2. Search existing issues
  3. Open a new issue with diagnostic output