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>
1.4 KiB
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 pushorbd dolt pullhangs 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 stopbefore system shutdown