beads/website/docs/reference/troubleshooting.md
Amp a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
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>
2026-03-11 13:25:40 -07:00

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