beads/website/docs/recovery/sync-failures.md
maphew 39e2b40109 docs: reconcile bd doctor --fix contradiction between architecture and recovery pages
Fix #2084: Architecture page said 'Never Use bd doctor --fix' while
recovery pages recommended it as a standard step. Reconciled by:

- Architecture: Downgrade from 'danger/never' to 'warning/use with care',
  add backup + dry-run precautions, explain the actual risk (circular dep
  false positives)
- Recovery pages: Add backup and --dry-run steps before --fix, creating a
  consistent decision tree across all docs
- Also fix stale references in recovery pages: SQLite → Dolt terminology,
  bd sync → bd dolt push/pull, bd dolt start → dolt sql-server

Amp-Thread-ID: https://ampcode.com/threads/T-019ca749-d4f2-7289-b085-52e17436e950
Co-authored-by: Amp <amp@ampcode.com>
2026-02-28 19:58:29 -07:00

1.4 KiB

sidebar_position title description
5 Sync Failures Recover from Dolt sync failures

Sync Failures Recovery

This runbook helps you recover from Dolt sync failures.

Symptoms

  • bd dolt push or bd dolt pull hangs or times out
  • Network-related error messages
  • "failed to push" or "failed to pull" errors
  • Dolt server not responding

Diagnosis

# Check Dolt server health
bd doctor
bd dolt show

# View Dolt server logs
tail -50 .beads/dolt/sql-server.log

Solution

Step 1: Stop the Dolt server

bd dolt stop

Step 2: Check for lock files

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

Step 3: Back up and preview fixes

cp -r .beads .beads.backup
bd doctor --dry-run

Step 4: Apply fixes if needed

bd doctor --fix

Step 5: Restart the Dolt server

dolt sql-server

Step 6: Verify sync works

bd dolt push
bd doctor

Common Causes

Cause Solution
Network timeout Retry with better connection
Stale lock file Remove lock after stopping Dolt server
Corrupted state Back up, then bd doctor --fix
Merge conflicts See Merge Conflicts

Prevention

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