Systematic cleanup of stale documentation references left over from the Dolt migration: - Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files - Replace all 'bd import' → 'bd init --from-jsonl' or remove - Replace 'bd init --branch' → note about refs/dolt/data separation - Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly) - Fix npm-package, claude-plugin, integrations, examples, website docs Add scripts/check-doc-flags.sh to catch stale doc references: - Checks for removed commands (bd sync, bd import) - Checks for removed flags (bd init --branch) - Warns on legacy SQLite/beads.db references - Compares CLI_REFERENCE.md against bd help --all Add CI job (check-doc-flags) and Makefile target (check-docs) to gate PRs against doc freshness. Prior art: feat/help-doc-generator branch has bd help --doc/--list for generating docs FROM CLI output. This script validates docs AGAINST CLI output — complementary approaches. Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6 Co-authored-by: Amp <amp@ampcode.com>
2.7 KiB
2.7 KiB
| id | title | sidebar_position |
|---|---|---|
| troubleshooting | Troubleshooting | 4 |
Troubleshooting
Common issues and solutions.
Installation Issues
bd: command not found
# Check if installed
which bd
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH
export PATH="$PATH:$(go env GOPATH)/bin"
# Or reinstall
go install github.com/steveyegge/beads/cmd/bd@latest
zsh: killed bd on macOS
CGO/SQLite compatibility issue:
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
Permission denied
chmod +x $(which bd)
Database Issues
Database not found
# Initialize beads
bd init --quiet
# Or specify database
bd --db .beads/beads.db list
Database locked
# Stop the Dolt server if running
bd dolt stop
# Try again
bd list
Corrupted database
# Check and fix database
bd doctor --fix
# Or pull from Dolt remote
bd dolt pull
# Or bootstrap from a JSONL backup if available
bd init --from-jsonl backup.jsonl
Dolt Server Issues
Server not starting
# Check server health
bd doctor
# Check server logs
cat .beads/dolt/sql-server.log
# Restart the server
bd dolt stop
bd dolt start
Version mismatch
After upgrading bd:
bd dolt stop
bd dolt start
Sync Issues
Changes not syncing
# Force push to Dolt remote
bd dolt push
# Check hooks
bd hooks status
Recovery from backup
# Bootstrap from JSONL backup
bd init --from-jsonl backup.jsonl
# Or pull from Dolt remote
bd dolt pull
Merge conflicts
# Check for and fix Dolt conflicts
bd doctor --fix
# Re-push
bd dolt push
Git Hook Issues
Hooks not running
# Check if installed
ls -la .git/hooks/
# Reinstall
bd hooks install
Hook errors
# Check hook script
cat .git/hooks/pre-commit
# Run manually
.git/hooks/pre-commit
Dependency Issues
Circular dependencies
# Detect cycles
bd dep cycles
# Remove one dependency
bd dep remove bd-A bd-B
Missing dependencies
# Check orphan handling
bd config get import.orphan_handling
# Allow orphans
bd config set import.orphan_handling allow
Performance Issues
Slow queries
# Check database size
ls -lh .beads/beads.db
# Compact if large
bd admin compact --analyze
High memory usage
# Reduce cache
bd config set database.cache_size 1000
Getting Help
Debug output
bd --verbose list
Logs
cat .beads/dolt/sql-server.log
System info
bd info --json
File an issue
# Include this info
bd version
bd info --json
uname -a
Report at: https://github.com/steveyegge/beads/issues