Skip to main content
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-server.log   # server mode

​
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

CauseSolution
Network timeoutRetry with better connection
Stale lock fileRemove lock after stopping Dolt server
Corrupted stateBack up, then bd doctor --fix
Merge conflictsSee Merge Conflicts

​
Prevention

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