docs/TROUBLESHOOTING.md
Common issues and solutions for bd users.
bd supports several environment variables for debugging specific subsystems. Enable these when troubleshooting issues or when requested by maintainers.
| Variable | Purpose | Output Location | Usage |
|---|---|---|---|
BD_DEBUG | General debug logging | stderr | Set to any value to enable |
BD_DEBUG_RPC | RPC communication between CLI and Dolt server | stderr | Set to 1 or true |
BD_DEBUG_SYNC | Sync and import timestamp protection | stderr | Set to any value to enable |
BD_DEBUG_ROUTING | Issue routing and multi-repo resolution | stderr | Set to any value to enable |
BD_DEBUG_FRESHNESS | Database file replacement detection | server logs | Set to any value to enable |
General debugging:
# Enable all general debug logging
export BD_DEBUG=1
bd ready
RPC communication issues:
# Debug Dolt server communication
export BD_DEBUG_RPC=1
bd list
# Example output:
# [RPC DEBUG] Connecting to Dolt server
# [RPC DEBUG] Sent request: list (correlation_id=abc123)
# [RPC DEBUG] Received response: 200 OK
Sync conflicts:
# Debug timestamp protection during sync
export BD_DEBUG_SYNC=1
bd dolt push
# Example output:
# [debug] Protected bd-123: local=2024-01-20T10:00:00Z >= incoming=2024-01-20T09:55:00Z
Routing issues:
# Debug issue routing in multi-repo setups
export BD_DEBUG_ROUTING=1
bd create "Test issue" --rig=planning
# Example output:
# [routing] Rig "planning" -> prefix plan, path /path/to/planning-repo (townRoot=/path/to/town)
# [routing] ID plan-123 matched prefix plan -> /path/to/planning-repo/beads
Database reconnection issues:
# Debug database file replacement detection
export BD_DEBUG_FRESHNESS=1
bd dolt start
# Example output:
# [freshness] FreshnessChecker: inode changed 27548143 -> 7945906
# [freshness] FreshnessChecker: triggering reconnection
# [freshness] Database file replaced, reconnection triggered
# Or check server logs
tail -f .beads/dolt/sql-server.log | grep freshness
Multiple debug flags:
# Enable multiple subsystems
export BD_DEBUG=1
export BD_DEBUG_RPC=1
export BD_DEBUG_FRESHNESS=1
bd dolt start
Disable after debugging: Debug logging can be verbose. Disable by unsetting the variable:
unset BD_DEBUG
unset BD_DEBUG_RPC
# etc.
Capture debug output: Redirect stderr to a file for analysis:
BD_DEBUG=1 bd dolt push 2> debug.log
Server logs: BD_DEBUG_FRESHNESS output goes to server logs, not stderr:
# View Dolt server logs
tail -f .beads/dolt/sql-server.log
When filing bug reports: Include relevant debug output to help maintainers diagnose issues faster.
bd: command not foundbd 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
If bd version shows an unexpected version (e.g., older than what you just installed), you likely have multiple bd binaries in your PATH.
Diagnosis:
# Check all bd binaries in PATH
which -a bd
# Example output showing conflict:
# /Users/you/go/bin/bd <- From go install (older)
# /opt/homebrew/bin/bd <- From Homebrew (newer)
Solution:
# Remove old go install version
rm ~/go/bin/bd
# Or remove mise-managed Go installs
rm ~/.local/share/mise/installs/go/*/bin/bd
# Verify you're using the correct version
which bd # Should show /opt/homebrew/bin/bd or your package manager path
bd version # Should show the expected version
Why this happens: If you previously installed bd via go install, the binary was placed in ~/go/bin/. When you later install via Homebrew or another package manager, the old ~/go/bin/bd may appear earlier in your PATH, causing the wrong version to run.
Recommendation: Choose one installation method (Homebrew recommended) and stick with it. Avoid mixing go install with package managers.
zsh: killed bd or crashes on macOSSome users report crashes when running bd init or other commands on macOS. 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
# Or if building from source
git clone https://github.com/gastownhall/beads
cd beads
CGO_ENABLED=1 go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please file an issue.
Symptom: Kaspersky, Windows Defender, or other antivirus software detects bd or bd.exe as a trojan or malicious software and removes it.
Common detections:
PDM:Trojan.Win32.GenericCause: This is a false positive. Go binaries are commonly flagged by antivirus heuristics because some malware is written in Go. This is a known industry-wide issue affecting many legitimate Go projects.
Solutions:
Verify file integrity first:
# Windows PowerShell
Get-FileHash bd.exe -Algorithm SHA256
# macOS/Linux
shasum -a 256 bd
Compare with checksums from the GitHub release page
Add bd to antivirus exclusions only after verification:
Report the false positive:
Detailed guide: See docs/ANTIVIRUS.md for complete instructions including:
Symptom: Running bd init or bd commands in a second project fails or connects to the wrong database. Multiple dolt sql-server processes are running.
Cause: By default, each beads project starts its own Dolt server. On machines with multiple projects, this can cause port conflicts or resource waste.
Fix: Enable shared server mode so all projects use a single Dolt server:
# Option 1: Machine-wide (add to ~/.bashrc or ~/.zshrc)
export BEADS_DOLT_SHARED_SERVER=1
# Option 2: Per-project
cd ~/project1 && bd dolt set shared-server true
cd ~/project2 && bd dolt set shared-server true
After enabling, existing projects may need bd init --force -q to create their database on the shared server.
Verify: bd dolt status from any project should show the same PID, port 3308, and ~/.beads/shared-server/ as the data directory.
bd shows 0 issues but the database has dataSymptom: All bd commands return empty results. bd list shows nothing.
Cause: Your bd may be connecting to a different Dolt server or database than expected. Before the version including the shadow DB fix (see CHANGELOG), bd unconditionally ran CREATE DATABASE IF NOT EXISTS on every connection, which could create an empty shadow database on the wrong server.
Diagnosis:
# Check what server bd is connecting to
cat .beads/metadata.json | grep -E "dolt_mode|dolt_server"
# Check if the database exists on the expected server
dolt sql -q "SHOW DATABASES" --host 127.0.0.1 --port 3307
# Query your data directly to confirm it exists
cd /path/to/your/dolt/data/beads_myproject
dolt sql -q "SELECT COUNT(*) FROM issues"
# Run diagnostics
bd doctor --server
Fix:
bd to a version including the shadow DB fix (see CHANGELOG)metadata.json points to the right server and port.beads/dolt/ directory exists alongside server mode, remove it:
rm -rf .beads/dolt/
Symptom (after shadow DB fix): bd returns "database not found on Dolt server" when the configured server is down.
Cause: When metadata.json has an explicit dolt_server_port, auto-start is intentionally disabled. Starting a different server would create a shadow database.
Fix:
# Start your configured Dolt server
bd dolt start
# Or start manually with the correct data directory
dolt sql-server --host 127.0.0.1 --port 3307 --data-dir /path/to/your/dolt/data
If you want auto-start behavior, remove dolt_server_port from .beads/metadata.json.
Symptom: After a system restart, bd reports that the Dolt server started
but is not accepting connections, and .beads/dolt-server.log contains:
possible data loss detected in journal file at offset ...: corrupted journal
Cause: Dolt detected damaged journal blocks after an unclean shutdown. This
is not the same as a stale PID, stale port, or stale lock file. bd will not
run Dolt's data-loss repair mode automatically.
Safe recovery when your remote is current:
mv .beads/dolt .beads/dolt.corrupt.$(date +%Y%m%dT%H%M%S)
bd bootstrap --dry-run
bd bootstrap --yes
bd stats
If the remote may be stale, keep the corrupt directory for forensics and inspect
it with dolt fsck before considering dolt fsck --revive-journal-with-data-loss.
Only use the revive path after reviewing Dolt's data-loss warning.
database is lockedAnother bd process is accessing the database. Solutions:
# Find and kill hanging processes
ps aux | grep bd
kill <pid>
# WARNING: Do NOT remove files inside .dolt/ directories (including noms/LOCK).
# These are Dolt-internal files — removing them WILL cause unrecoverable
# data corruption. Dolt manages these files itself.
# For server mode: restart the Dolt server
# (server mode handles concurrent access natively)
Note: For high-concurrency scenarios (multiple agents), use Dolt server mode (bd dolt set mode server) which handles concurrent access natively via dolt sql-server.
bd init fails with "directory not empty".beads/ already exists. Options:
# Use existing database
bd list # Should work if already initialized
# Or remove and reinitialize (DESTROYS DATA!)
rm -rf .beads/
bd init
failed to import: issue already existsYou're trying to bootstrap a database with issues that conflict with existing ones. Options:
# Clear database and re-initialize from an export
rm -rf .beads/dolt
bd init --from-jsonl
If you see errors like parent issue bd-abc does not exist when bootstrapping from JSONL or pulling hierarchical issues (e.g., bd-abc.1, bd-abc.2), this means the parent issue was deleted but children still reference it.
Quick fix using resurrection:
# Set orphan handling to auto-resurrect deleted parents
bd config set import.orphan_handling "resurrect"
# Then pull or re-initialize
bd dolt pull
What resurrection does:
Other handling modes:
# Allow orphans (default) - import without validation
bd config set import.orphan_handling "allow"
# Skip orphans - partial import with warnings
bd config set import.orphan_handling "skip"
# Strict - fail fast on missing parents
bd config set import.orphan_handling "strict"
When this happens:
bd deletePrevention:
bd delete --cascade to also delete childrenbd list --id bd-abc.*See CONFIG.md for complete configuration documentation.
Symptom: After running bd admin reset --force and bd init, old issues reappear.
Cause: bd admin reset --force only removes local beads data. Old data can return from:
Solution for complete clean slate:
# 1. Reset local beads
bd admin reset --force
# 2. Delete remote sync branch (if configured)
# Check your sync branch name first:
bd config get sync.branch
# Then delete it from remote:
git push origin --delete <sync-branch-name>
# Common names: beads-sync, beads-metadata
# 3. Re-initialize
bd init
Less destructive alternatives:
# Option A: Just delete the sync branch and reinit
bd admin reset --force
git push origin --delete beads-sync # or your sync branch name
bd init
# Option B: Start fresh without sync branch
bd admin reset --force
bd init
bd config set sync.branch "" # Disable sync branch feature
Note: The --hard and --skip-init flags mentioned in GH#479 were never implemented. Use the workarounds above for a complete reset.
Related: GH#922
Important: Distinguish between logical consistency issues (ID collisions, wrong prefixes) and physical database corruption.
For physical database corruption (disk failures, power loss, filesystem errors):
# If corrupted, rebuild from a Dolt remote or from a backup snapshot
mv .beads/dolt .beads/dolt.backup
bd init
bd dolt pull # Pull from Dolt remote if configured
# Or restore from a backup:
# bd backup restore [path] --force
For logical consistency issues (ID collisions from branch merges, parallel workers):
# This is NOT corruption - use Dolt merge or bd doctor --fix
bd doctor --fix
See FAQ for the distinction.
If you see a warning about multiple .beads databases in the directory hierarchy:
╔══════════════════════════════════════════════════════════════════════════╗
║ WARNING: 2 beads databases detected in directory hierarchy ║
╠══════════════════════════════════════════════════════════════════════════╣
║ Multiple databases can cause confusion and database pollution. ║
║ ║
║ ▶ /path/to/project/.beads (15 issues) ║
║ /path/to/parent/.beads (32 issues) ║
║ ║
║ Currently using the closest database (▶). This is usually correct. ║
║ ║
║ RECOMMENDED: Consolidate or remove unused databases to avoid confusion. ║
╚══════════════════════════════════════════════════════════════════════════╝
This means bd found multiple .beads directories in your directory hierarchy. The ▶ marker shows which database is actively being used (usually the closest one to your current directory).
Why this matters:
Solutions:
If you have nested projects (intentional):
BEADS_DIR environment variable to point to your .beads directory if you want to override the default selectionBEADS_DB (deprecated) to point directly to the database fileIf you have accidental duplicates (unintentional):
cd <unwanted-dir> && bd export -o backup.jsonl.beads directory: rm -rf <unwanted-dir>/.beadsOverride database selection:
# Temporarily use specific .beads directory (recommended)
BEADS_DIR=/path/to/.beads bd list
# Or add to shell config for permanent override
export BEADS_DIR=/path/to/.beads
# Legacy method (deprecated, points to database file directly)
BEADS_DB=/path/to/.beads/issues.db bd list
export BEADS_DB=/path/to/.beads/issues.db
Note: The warning only appears when bd detects multiple databases. If you see this consistently and want to suppress it, you're using the correct database (marked with ▶).
Symptom: Every bd command fails with dolt circuit breaker is open: server appears down, failing fast (cooldown 30s). This persists across repeated invocations.
Cause: The circuit breaker tripped after repeated connection failures. Its state is stored in a file at /tmp/beads-dolt-circuit-<host>-<port>.json (keyed on host:port) and shared across all bd processes. Once tripped, all commands to that specific host:port are rejected until a successful probe resets it.
Note: bd dolt status checks the server's PID file, not whether the server is actually accepting connections. A "running" status does not guarantee the server is reachable on the expected port.
Diagnosis:
# Check circuit breaker state
cat /tmp/beads-dolt-circuit-*.json
# Check if the Dolt server is actually listening
lsof -i :<port>
# Compare configured port with what's actually running
cat .beads/metadata.json | grep port
Fix:
rm /tmp/beads-dolt-circuit-*.json
bd dolt stop
bd dolt start
bd list
Note (macOS): On macOS, /tmp is a symlink to /private/tmp. The circuit breaker state file may persist across reboots since /private/tmp is not always cleared on restart.
Symptom: After upgrading from v0.49 or earlier to v0.58+, bd commands fail with connection errors or the circuit breaker trips on first run.
Cause: Pre-Dolt versions used SQLite for storage. The Dolt backend requires a running Dolt server. On first run after upgrading, the server may not be configured or started yet.
Fix:
scripts/migrate-jsonl-to-dolt.sh
bd dolt start
bd list
Dolt handles merge conflicts natively with cell-level merge. When concurrent changes affect the same issue field, Dolt detects the conflict and allows resolution via SQL:
# Check for conflicts after a Dolt 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.
See ADVANCED.md#handling-git-merge-conflicts for details.
Symptom: After bd hooks install, chained pre-commit hooks (eslint, prettier, ruff, etc.) stop running. You see: beads: hook 'pre-commit' timed out after 300s -- continuing without beads.
Cause: The beads hook shim wraps bd hooks run with an OS-level timeout. Since bd hooks run chains to your original hook (.git/hooks/pre-commit.old) internally, the timeout covers both beads' own work and your entire hook pipeline.
Fix: Increase the timeout via the BEADS_HOOK_TIMEOUT environment variable:
# Add to ~/.bashrc or ~/.zshrc
export BEADS_HOOK_TIMEOUT=600 # 10 minutes (in seconds)
The default timeout is 300 seconds (5 minutes). For repos with very heavy pre-commit pipelines, you may need to increase this further.
Git hooks need execute permissions:
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/post-merge
chmod +x .git/hooks/post-checkout
Symptom:
$ git checkout main
fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
Cause: Beads previously created git worktrees internally for a sync-branch feature (configured via bd config set sync.branch). These worktrees lock the branches they're checked out to. This feature has been removed; Dolt now stores data under refs/dolt/data, separate from standard Git refs.
Solution:
# Remove beads-created worktrees
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
# Now you can checkout the branch
git checkout main
Permanent fix (disable sync-branch):
bd config set sync.branch ""
See WORKTREES.md#beads-created-worktrees-sync-branch for details.
Symptom: You notice .git/beads-worktrees/ or .git/worktrees/beads-* directories you didn't create.
Explanation: Beads automatically creates these worktrees when using the sync-branch feature to commit issue updates to a separate branch without switching your working directory.
If you don't want these:
# Disable sync-branch feature
bd config set sync.branch ""
# Clean up existing worktrees
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
See WORKTREES.md for details on how beads uses worktrees.
Check if Dolt server is running and configured:
# Check if Dolt server is running
bd doctor
# Manual sync with Dolt remotes
bd dolt push
bd dolt pull
# Check sync configuration
bd config get sync.remote
bd ready shows nothing but I have open issuesThose issues probably have open blockers. Check:
# See blocked issues
bd blocked
# Show dependency tree (default max depth: 50)
bd dep tree <issue-id>
# Limit tree depth to prevent deep traversals
bd dep tree <issue-id> --max-depth 10
# Remove blocking dependency if needed
bd dep remove <from-id> <to-id>
Remember: Only blocks dependencies affect ready work.
bd prevents dependency cycles, which break ready work detection. To fix:
# Detect all cycles
bd dep cycles
# Remove the dependency causing the cycle
bd dep remove <from-id> <to-id>
# Or redesign your dependency structure
Check the dependency type:
# Show full issue details including dependencies
bd show <issue-id>
# Visualize the dependency tree
bd dep tree <issue-id>
Remember: Different dependency types have different meanings:
blocks - Hard blocker, affects ready workrelated - Soft relationship, doesn't blockparent-child - Hierarchical (child depends on parent)discovered-from - Work discovered during another issueFor 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
Consider splitting large projects into multiple databases.
Check database size and consider compaction:
# 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
Agents may not realize an issue already exists. Prevention strategies:
bd list --json | grep "title"bd create "..." -l auto-generatedbd list | sortbd merge to consolidate duplicates: bd merge bd-2 --into bd-1Simplify the dependency structure:
# Check for overly complex trees
bd dep tree <issue-id>
# Remove unnecessary dependencies
bd dep remove <from-id> <to-id>
# Use labels instead of dependencies for loose relationships
bd label add <issue-id> related-to-feature-X
Check if issues are blocked:
# See what's blocked
bd blocked
# See what's actually ready
bd ready --json
# Check specific issue
bd show <issue-id>
bd dep tree <issue-id>
Check installation and configuration:
# Verify MCP server is installed
pip list | grep beads-mcp
# Check MCP configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Test CLI works
bd version
bd ready
# Check Dolt server health
bd doctor
See integrations/beads-mcp/README.md for MCP-specific troubleshooting.
Issue: Sandboxed environments restrict permissions, preventing server control and causing "out of sync" errors.
Common symptoms:
bd dolt pullbd dolt stop fails with "operation not permitted"Root cause: The sandbox can't signal/kill the existing Dolt server process.
As of v0.21.1+, bd automatically detects sandboxed environments and enables sandbox mode.
When auto-detected, you'll see: ℹ️ Sandbox detected, using direct mode
Manual override (if auto-detection fails):
# Explicitly enable sandbox mode
bd --sandbox ready
bd --sandbox create "Fix bug" -p 1
bd --sandbox update bd-42 --claim
What sandbox mode does:
Note: You'll need to manually sync when outside the sandbox:
# After leaving sandbox, sync manually
bd dolt push
If you're stuck in a "database out of sync" loop with a running server you can't stop, use these flags:
1. Force metadata update
If staleness persists after pulling:
# Force metadata refresh
bd doctor --fix
# This updates internal metadata tracking without changing issues
# Fixes: stuck state caused by stale server cache
2. Use sandbox mode (preferred)
# Most reliable for sandboxed environments
bd --sandbox ready
bd --sandbox dolt pull
If stuck in a sandboxed environment:
# Step 1: Try sandbox mode (cleanest solution)
bd --sandbox ready
# Step 2: If you get staleness errors, force fix
bd doctor --fix
# Step 3: When back outside sandbox, sync normally
bd dolt push
| Flag | Purpose | When to use | Risk |
|---|---|---|---|
--sandbox | Use embedded mode, disable auto-sync | Sandboxed environments (Codex, containers) | Low - safe for sandboxes |
bd doctor --fix | Force metadata update | Stuck staleness loop | Low - updates metadata only |
Related:
# 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
)
# Reload PATH in current session
$env:Path = [Environment]::GetEnvironmentVariable("Path", "User")
The Dolt server listens on loopback TCP. Allow bd.exe through Windows Firewall:
bd.exe and enable for Private networksSymptom: bd init hangs indefinitely with high CPU usage, and CTRL+C doesn't work.
Cause: Windows Controlled Folder Access is blocking bd.exe from creating the .beads directory.
Diagnosis: Run with verbose flag to see the actual error:
bd init -v
# Error: failed to create .beads directory: mkdir .beads: The system cannot find the file specified
Solution: Add bd.exe to the Controlled Folder Access whitelist:
bd.exe (typically in %USERPROFILE%\go\bin\bd.exe)bd init - it should work instantlyNote: Unlike typical blocked apps, Controlled Folder Access may not show a notification when blocking bd init, making this issue hard to diagnose without the -v flag.
If macOS blocks bd:
checksums.txt.scripts/install.sh, note that macOS ad-hoc re-signing is now opt-in (BEADS_INSTALL_RESIGN_MACOS=1).# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/bd
# Or allow in System Preferences
# System Preferences → Security & Privacy → General → "Allow anyway"
If you get permission errors:
# 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"
If none of these solutions work:
bd --verbose <command>bd versionuname -a