Skip to main content

​
Debug Environment Variables

bd supports several environment variables for debugging specific subsystems. Enable these when troubleshooting issues.
VariablePurposeUsage
BD_DEBUGGeneral debug loggingSet to any value
BD_DEBUG_RPCRPC communicationSet to 1 or true
BD_DEBUG_SYNCSync and timestamp protectionSet to any value
BD_DEBUG_ROUTINGIssue routing (multi-repo)Set to any value
BD_DEBUG_FRESHNESSDatabase reconnectionSet to any value
Example usage: 
# Enable RPC debugging
export BD_DEBUG_RPC=1
bd list

# Debug sync conflicts
export BD_DEBUG_SYNC=1
bd sync

# Multiple debug flags
export BD_DEBUG=1 BD_DEBUG_RPC=1
bd dolt start
Disable debug logging after troubleshooting: unset BD_DEBUG BD_DEBUG_RPC

​
Installation Issues

​
bd: command not found

bd is not in your PATH. Either: 
# Check if installed
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd

# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(go env GOPATH)/bin"

# Or reinstall
go install github.com/steveyegge/beads/cmd/bd@latest

​
Wrong version running

If bd version shows an unexpected version, you likely have multiple bd binaries in your PATH. Diagnosis: 
# Check all bd binaries
which -a bd

# Example conflict:
# /Users/you/go/bin/bd        <- older
# /opt/homebrew/bin/bd        <- newer
Solution: 
# Remove old version
rm ~/go/bin/bd

# Or remove mise-managed installs
rm ~/.local/share/mise/installs/go/*/bin/bd

# Verify
which bd
bd version
Choose one installation method (Homebrew recommended) and stick with it. Avoid mixing go install with package managers.

​
Crashes on macOS

Some users report crashes when running bd init or other commands. This is typically caused by CGO/SQLite compatibility issues. Workaround: 
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest

​
Antivirus False Positives

Antivirus software (Kaspersky, Windows Defender) may flag bd as malware. This is a false positive common with Go binaries. Solutions:
  1. Add bd to antivirus exclusions (recommended)
  2. Verify file integrity before excluding: 
    # Windows PowerShell
Get-FileHash bd.exe -Algorithm SHA256

# macOS/Linux
shasum -a 256 bd
    Compare with checksums from the GitHub release page
  3. Report false positive to your antivirus vendor
For complete instructions, see the Antivirus Guide.

​
Database Issues

​
bd shows 0 issues but database has data

Symptom: All bd commands return empty results. Diagnosis: 
# Check server connection
cat .beads/metadata.json | grep -E "dolt_mode|dolt_server"

# Check databases
dolt sql -q "SHOW DATABASES" --host 127.0.0.1 --port 3307

# Run diagnostics
bd doctor --server
Fix:
  1. Upgrade bd to latest version
  2. Ensure Dolt server is running from correct directory
  3. Verify metadata.json points to right server
  4. Remove stale .beads/dolt/ directory if exists alongside server mode: 
    rm -rf .beads/dolt/

​
Database is locked

Another bd process is accessing the database. 
# Find and kill hanging processes
ps aux | grep bd
kill <pid>

# Remove stale lock file
rm .beads/dolt/.dolt/lock

# For server mode: restart Dolt server
bd dolt stop
bd dolt start
For high-concurrency scenarios (multiple agents), use Dolt server mode which handles concurrent access natively.

​
Import fails with missing parent errors

If you see errors like parent issue bd-abc does not exist when importing hierarchical issues: Quick fix using resurrection: 
# Auto-resurrect deleted parents from import data
bd import -i issues.jsonl --orphan-handling resurrect

# Or set as default
bd config set import.orphan_handling "resurrect"
What resurrection does:
  1. Searches import data for missing parent issue
  2. Recreates it as tombstone (Status=Closed, Priority=4)
  3. Preserves parent’s original title and description
  4. Maintains referential integrity for children
Other handling modes: 
# Allow orphans (default)
bd config set import.orphan_handling "allow"

# Skip orphans
bd config set import.orphan_handling "skip"

# Strict - fail on missing parents
bd config set import.orphan_handling "strict"

​
Old data returns after reset

Symptom: After bd admin reset --force, old issues reappear. Cause: Reset only removes local data. Old data can return from:
  1. Dolt remotes - Old data may exist there
  2. Remote sync branch - Old data on remote
  3. Other machines - Other clones may push old data
Complete clean slate: 
# 1. Reset local beads
bd admin reset --force

# 2. Delete remote sync branch
bd config get sync.branch  # Check name first
git push origin --delete <sync-branch-name>

# 3. Re-initialize
bd init

​
Database corruption

Distinguish between logical consistency issues (ID collisions) and physical database corruption (disk failures).
For physical database corruption: 
# Rebuild from Dolt remote or backup
mv .beads/dolt .beads/dolt.backup
bd init
bd dolt pull  # Pull from Dolt remote
# Or: bd import -i backup.jsonl
For logical consistency issues: 
# Use doctor --fix
bd doctor --fix

​
Git and Sync Issues

​
Merge conflicts

Dolt handles merge conflicts natively with cell-level merge. 
# Check for conflicts after pull
bd dolt pull

# Resolve conflicts if any
bd vc conflicts
With hash-based IDs (v0.20.1+), ID collisions don’t occur. Different issues get different hash IDs.

​
”Branch already checked out” when switching branches

Symptom: 
$ git checkout main
fatal: 'main' is already checked out at '/path/.git/beads-worktrees/beads-sync'
Cause: Beads creates git worktrees when using sync-branch feature. Solution: 
# Remove beads-created worktrees
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune

# Disable sync-branch (permanent fix)
bd config set sync.branch ""

​
Auto-sync not working

# Check Dolt server status
bd doctor

# Manual sync
bd dolt push
bd dolt pull

# Check configuration
bd config get sync.mode

​
Ready Work and Dependencies

​
bd ready shows nothing but I have open issues

Those issues probably have open blockers. 
# See blocked issues
bd blocked

# Show dependency tree
bd dep tree <issue-id>

# Limit tree depth
bd dep tree <issue-id> --max-depth 10

# Remove blocking dependency if needed
bd dep remove <from-id> <to-id>
Only blocks dependencies affect ready work.

​
Circular dependency errors

bd prevents dependency cycles which break ready work detection. 
# Detect all cycles
bd dep cycles

# Remove dependency causing cycle
bd dep remove <from-id> <to-id>

​
Dependencies not showing up

Check the dependency type: 
# Show full issue details
bd show <issue-id>

# Visualize dependency tree
bd dep tree <issue-id>
Dependency types:
  • blocks - Hard blocker, affects ready work
  • related - Soft relationship, doesn’t block
  • parent-child - Hierarchical (child depends on parent)
  • discovered-from - Work discovered during another issue

​
Performance Issues

​
Export/import is slow

For large databases (10k+ issues): 
# Export only open issues
bd export --format=jsonl --status=open -o open-issues.jsonl

# Or filter by priority
bd export --format=jsonl --priority=0 --priority=1 -o critical.jsonl

​
Commands are slow

# Check database stats
bd stats

# Preview compaction candidates
bd admin compact --dry-run --all

# Compact old closed issues
bd admin compact --days 90

# Run Dolt garbage collection
cd .beads/dolt && dolt gc
Consider splitting large projects into multiple databases: 
cd ~/project/component1 && bd init --prefix comp1
cd ~/project/component2 && bd init --prefix comp2

​
Agent-Specific Issues

​
Agent creates duplicate issues

Prevention strategies:
  • Have agents search first: bd list --json | grep "title"
  • Use labels to mark auto-created issues: bd create "..." -l auto-generated
  • Review and deduplicate periodically
  • Use bd merge to consolidate: bd merge bd-2 --into bd-1

​
Agent can’t find ready work

# See what's blocked
bd blocked

# See what's ready
bd ready --json

# Check specific issue
bd show <issue-id>
bd dep tree <issue-id>

​
Sandboxed environments (Codex, Claude Code)

Issue: Sandboxed environments restrict permissions, causing “out of sync” errors. Quick fix: Sandbox mode (auto-detected in v0.21.1+) 
# Explicitly enable sandbox mode
bd --sandbox ready
bd --sandbox create "Fix bug" -p 1
What sandbox mode does:
  • Uses embedded database mode (no server needed)
  • Disables auto-export/import
  • Works in network-restricted environments
Escape hatches for stuck states: 
# Force metadata update
bd import --force

# Skip staleness check (emergency)
bd --allow-stale ready

# Use sandbox mode (preferred)
bd --sandbox ready
Use --allow-stale sparingly - you may see incomplete or outdated data.

​
Platform-Specific Issues

​
Windows: Path issues

# Check if bd.exe is in PATH
where.exe bd

# Add Go bin to PATH (permanently)
[Environment]::SetEnvironmentVariable(
    "Path",
    $env:Path + ";$env:USERPROFILE\go\bin",
    [EnvironmentVariableTarget]::User
)

​
Windows: Controlled Folder Access blocks bd init

Symptom: bd init hangs indefinitely with high CPU. Solution: Add bd.exe to Controlled Folder Access whitelist:
  1. Open Windows Security → Virus & threat protection
  2. Click “Ransomware protection” → “Manage ransomware protection”
  3. Under “Controlled folder access”, click “Allow an app”
  4. Add bd.exe (typically in %USERPROFILE%\go\bin\bd.exe)
  5. Retry bd init

​
macOS: Gatekeeper blocking execution

# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/bd

# Or allow in System Preferences → Security & Privacy

​
Linux: Permission denied

# Make bd executable
chmod +x /usr/local/bin/bd

# Or install to user directory
mkdir -p ~/.local/bin
mv bd ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

​
Getting Help

If none of these solutions work:
  1. Check existing issues: GitHub Issues
  2. Enable debug logging: Use the debug environment variables above
  3. File a bug report including:
    • bd version: bd version
    • OS and architecture: uname -a
    • Error message and full command
    • Steps to reproduce
  4. Join discussions: GitHub Discussions

Build docs developers (and LLMs) love

Get started for freeTalk to us