Troubleshooting

Common issues and solutions for Beads users

Debug Environment Variables

bd supports several environment variables for debugging specific subsystems. Enable these when troubleshooting issues.

Variable	Purpose	Usage
BD_DEBUG	General debug logging	Set to any value
BD_DEBUG_RPC	RPC communication	Set to 1 or true
BD_DEBUG_SYNC	Sync and timestamp protection	Set to any value
BD_DEBUG_ROUTING	Issue routing (multi-repo)	Set to any value
BD_DEBUG_FRESHNESS	Database reconnection	Set 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