Troubleshooting

# Check if installed
which bd
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 with the recommended installer
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# 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)

# Remove the old go install version
rm ~/go/bin/bd

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

# Verify
which bd
bd version

CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go 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 -tags gms_pure_go -o bd ./cmd/bd
sudo mv bd /usr/local/bin/

chmod +x $(which bd)

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

# Initialize beads
bd init --quiet

# Or point bd at an existing .beads directory
BEADS_DIR=/path/to/.beads bd list

# Stop the Dolt server if running (server mode)
bd dolt stop

# Find and kill hanging bd processes
ps aux | grep bd
kill <pid>

# Try again
bd list

bd doctor --fix

# Move the damaged data directory aside:
mv .beads/embeddeddolt .beads/embeddeddolt.backup   # embedded mode (default)
mv .beads/dolt .beads/dolt.backup                   # server mode

bd init
bd dolt pull    # Pull from Dolt remote if configured

# Or restore from a backup:
# bd backup restore [path] --force

possible data loss detected in journal file at offset ...: corrupted journal

# Server mode data lives at .beads/dolt; embedded mode at .beads/embeddeddolt
mv .beads/dolt .beads/dolt.corrupt.$(date +%Y%m%dT%H%M%S)
bd bootstrap --dry-run
bd bootstrap --yes
bd stats

# DESTROYS the local database — export first if unsure
rm -rf .beads/embeddeddolt   # embedded mode (default)
rm -rf .beads/dolt           # server mode

bd init --from-jsonl

# Check what mode and server bd is using
cat .beads/metadata.json | grep -E "dolt_mode|dolt_server_port"

# Run server-mode health checks
bd doctor --server

# Confirm what the connected database contains
bd sql 'SELECT COUNT(*) FROM issues'

# 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

# Option 1: Machine-wide (add to ~/.bashrc or ~/.zshrc)
export BEADS_DOLT_SHARED_SERVER=1

# Option 2: Per-project
bd config set dolt.shared-server true

# Check circuit breaker state
cat /tmp/beads-circuit/beads-dolt-circuit-*.json

# Check if the Dolt server is actually listening
lsof -i :<port>

# Compare the configured port with what's running
cat .beads/metadata.json | grep port

rm /tmp/beads-circuit/beads-dolt-circuit-*.json
bd dolt stop
bd dolt start
bd list

# Check server health
bd doctor

# Check server logs (server mode; embedded mode runs in-process, no server log)
cat .beads/dolt-server.log

# Restart the server
bd dolt stop
bd dolt start

bd dolt stop
bd dolt start

# Force push to Dolt remote
bd dolt push

# Check hooks
bd hooks list

# Restore from a Dolt backup
bd backup restore [path] --force

# Or pull from Dolt remote
bd dolt pull

# Check for and fix Dolt conflicts
bd doctor --fix

# Re-push
bd dolt push

# Check if installed
ls -la .git/hooks/

# Reinstall
bd hooks install

# Check hook script
cat .git/hooks/pre-commit

# Run manually
.git/hooks/pre-commit

# Add to ~/.bashrc or ~/.zshrc
export BEADS_HOOK_TIMEOUT=600  # 10 minutes (in seconds)

chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/post-merge
chmod +x .git/hooks/post-checkout

# Confirm the bad entry: mode 120000 but Markdown content
git ls-files -s CLAUDE.md
git cat-file -p :CLAUDE.md | sed -n '1,5p'

# Convert the blob to a regular tracked file without changing content
sha=$(git rev-parse :CLAUDE.md)
git update-index --cacheinfo 100644,$sha,CLAUDE.md
git checkout-index -f -- CLAUDE.md

# Verify: first column should now be 100644
git ls-files -s CLAUDE.md
git diff -- CLAUDE.md

rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune

# See blocked issues
bd blocked

# Show the dependency tree (default max depth: 50)
bd dep tree <issue-id>
bd dep tree <issue-id> --max-depth 10

# Remove a blocking dependency if needed
bd dep remove <from-id> <to-id>

# Detect cycles
bd dep cycles

# Remove one dependency
bd dep remove bd-A bd-B

# Show full issue details including dependencies
bd show <issue-id>

# Visualize the dependency tree
bd dep tree <issue-id>

# Check database stats
bd stats

# Check on-disk size
du -sh .beads/embeddeddolt   # embedded mode (default)
du -sh .beads/dolt           # server mode

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

# Compact if large
bd admin compact --analyze

cd ~/project/component1 && bd init --prefix comp1
cd ~/project/component2 && bd init --prefix comp2

# Run Dolt garbage collection to compact storage
bd admin compact --dolt

Error 1105 (HY000): context canceled

# 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

# Verify the MCP server is installed
pip list | grep beads-mcp

# Check MCP configuration (Claude Desktop on macOS)
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Test that the CLI itself works
bd version
bd ready
bd doctor

bd --sandbox ready
bd --sandbox create "Fix bug" -p 1

bd dolt push

# 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")

bd init -v
# Error: failed to create .beads directory: mkdir .beads: The system cannot find the file specified

const { execFile } = require('node:child_process');

const isWindows = process.platform === 'win32';

execFile(
  isWindows ? 'bd.cmd' : 'bd',
  ['ready', '--json'],
  { shell: isWindows },
  (err, stdout) => { /* ... */ },
);

// From Node on Windows: no path conversion happens
execFile('bd.cmd', ['export', '-o', '/tmp/issues.jsonl'], { shell: true }, ...);
// bd writes C:\tmp\issues.jsonl — and exits 0

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

# Or: System Preferences → Security & Privacy → General → "Allow anyway"

# General debugging
BD_DEBUG=1 bd ready

# Capture debug output to a file
BD_DEBUG=1 bd dolt push 2> debug.log

# Sync timestamp protection, e.g.:
# [debug] Protected bd-123: local=2024-01-20T10:00:00Z >= incoming=2024-01-20T09:55:00Z
BD_DEBUG_SYNC=1 bd dolt push

# Freshness output goes to the server log (server mode), not stderr
BD_DEBUG_FRESHNESS=1 bd dolt start
tail -f .beads/dolt-server.log | grep freshness

bd --verbose list

# Server mode (embedded mode runs in-process, no server log)
cat .beads/dolt-server.log

bd info --json

# Include this info
bd version
bd info --json
uname -a