Skip to main content

Sync Failures Recovery

This runbook helps you recover from bd sync failures.

Symptoms​

  • bd sync hangs or times out
  • Network-related error messages
  • "failed to push" or "failed to pull" errors
  • Daemon not responding

Diagnosis​

# Check daemon status
bd daemon status

# Check sync state
bd status

# View daemon logs
cat .beads/daemon.log | tail -50

Solution​

Step 1: Stop the daemon

bd daemon stop

Step 2: Check for lock files

ls -la .beads/*.lock
# Remove stale locks if daemon is definitely stopped
rm -f .beads/*.lock

Step 3: Force a fresh sync

bd doctor --fix

Step 4: Restart daemon

bd daemon start

Step 5: Verify sync works

bd sync
bd status

Common Causes​

CauseSolution
Network timeoutRetry with better connection
Stale lock fileRemove lock after stopping daemon
Corrupted stateUse bd doctor --fix
Git conflictsSee Merge Conflicts

Prevention​

  • Ensure stable network before sync
  • Let sync complete before closing terminal
  • Use bd daemon stop before system shutdown