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

Prevention

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