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