# Troubleshooting bd

Common issues and solutions for bd users.

## Table of Contents

- [Debug Environment Variables](#debug-environment-variables)
- [Installation Issues](#installation-issues)
- [Antivirus False Positives](#antivirus-false-positives)
- [Database Issues](#database-issues)
  - [Circuit breaker: "server appears down, failing fast"](#circuit-breaker-server-appears-down-failing-fast)
  - [Connection failures after upgrading from pre-Dolt versions](#connection-failures-after-upgrading-from-pre-dolt-versions)
- [Git and Sync Issues](#git-and-sync-issues)
- [Ready Work and Dependencies](#ready-work-and-dependencies)
- [Performance Issues](#performance-issues)
- [Agent-Specific Issues](#agent-specific-issues)
- [Platform-Specific Issues](#platform-specific-issues)

## Debug Environment Variables

bd supports several environment variables for debugging specific subsystems. Enable these when troubleshooting issues or when requested by maintainers.

### Available Debug Variables

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

### Usage Examples

**General debugging:**
```bash
# Enable all general debug logging
export BD_DEBUG=1
bd ready
```

**RPC communication issues:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Enable multiple subsystems
export BD_DEBUG=1
export BD_DEBUG_RPC=1
export BD_DEBUG_FRESHNESS=1
bd dolt start
```

### Tips

- **Disable after debugging**: Debug logging can be verbose. Disable by unsetting the variable:
  ```bash
  unset BD_DEBUG
  unset BD_DEBUG_RPC
  # etc.
  ```

- **Capture debug output**: Redirect stderr to a file for analysis:
  ```bash
  BD_DEBUG=1 bd dolt push 2> debug.log
  ```

- **Server logs**: `BD_DEBUG_FRESHNESS` output goes to server logs, not stderr:
  ```bash
  # 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.

### Related Documentation

- [ROUTING.md](ROUTING.md) - Multi-repo routing configuration

## Installation Issues

### `bd: command not found`

bd is not in your PATH. Either:

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

### Wrong version of bd running / Multiple bd binaries in PATH

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:**
```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)
```

**Solution:**
```bash
# 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 macOS

Some users report crashes when running `bd init` or other commands on macOS. This is typically caused by CGO/SQLite compatibility issues.

**Workaround:**
```bash
# Install an embedded-capable build
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/
```

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](https://github.com/gastownhall/beads/issues).

## Antivirus False Positives

### Antivirus software flags bd as malware

**Symptom**: Kaspersky, Windows Defender, or other antivirus software detects `bd` or `bd.exe` as a trojan or malicious software and removes it.

**Common detections**:
- Kaspersky: `PDM:Trojan.Win32.Generic`
- Windows Defender: Various generic trojan detections

**Cause**: 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**:

1. **Verify file integrity first**:
   ```bash
   # Windows PowerShell
   Get-FileHash bd.exe -Algorithm SHA256

   # macOS/Linux
   shasum -a 256 bd
   ```
   Compare with checksums from the [GitHub release page](https://github.com/gastownhall/beads/releases)

2. **Add bd to antivirus exclusions only after verification**:
   - Add the bd installation directory to your antivirus exclusion list
   - Keep antivirus enabled for everything else

3. **Report the false positive**:
   - Help improve detection by reporting to your antivirus vendor
   - Most vendors have false positive submission forms

**Detailed guide**: See [docs/ANTIVIRUS.md](ANTIVIRUS.md) for complete instructions including:
- How to add exclusions for specific antivirus software
- How to report false positives to vendors
- Why Go binaries trigger these detections
- Future plans for code signing

## Database Issues

### Port conflicts with multiple projects

**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:

```bash
# 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 data

**Symptom:** 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](../CHANGELOG.md)), `bd` unconditionally ran `CREATE DATABASE IF NOT EXISTS` on every connection, which could create an empty shadow database on the wrong server.

**Diagnosis:**

```bash
# 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:**

1. Upgrade `bd` to a version including the shadow DB fix (see [CHANGELOG](../CHANGELOG.md))
2. Ensure your Dolt server is running from the correct data directory
3. Verify `metadata.json` points to the right server and port
4. If a stale `.beads/dolt/` directory exists alongside server mode, remove it:
   ```bash
   rm -rf .beads/dolt/
   ```

### Configured server unreachable (auto-start disabled)

**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:**

```bash
# 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`.

### Dolt journal corruption after restart

**Symptom:** After a system restart, `bd` reports that the Dolt server started
but is not accepting connections, and `.beads/dolt-server.log` contains:

```text
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:**

```bash
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 locked`

Another bd process is accessing the database. Solutions:

```bash
# 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:

```bash
# 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 exists`

You're trying to bootstrap a database with issues that conflict with existing ones. Options:

```bash
# Clear database and re-initialize from an export
rm -rf .beads/dolt
bd init --from-jsonl
```

### Import fails with missing parent errors

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:**

```bash
# 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:**

1. Searches the import data for the missing parent issue
2. Recreates it as a tombstone (Status=Closed, Priority=4)
3. Preserves the parent's original title and description
4. Maintains referential integrity for hierarchical children
5. Also resurrects dependencies on best-effort basis

**Other handling modes:**

```bash
# 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:**

- Parent issue was deleted using `bd delete`
- Branch merge where one side deleted the parent
- Manual editing that removed parent entries
- Database corruption or incomplete import

**Prevention:**

- Use `bd delete --cascade` to also delete children
- Check for orphans before cleanup: `bd list --id bd-abc.*`
- Review impact before deleting epic/parent issues

See [CONFIG.md](CONFIG.md#example-import-orphan-handling) for complete configuration documentation.

### Old data returns after reset

**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:

1. **Dolt remotes** - If you have configured Dolt remotes, old data may exist there
2. **Remote sync branch** - If you configured a sync branch, old data may exist on the remote
3. **Other machines** - Other clones may push old data after you reset

**Solution for complete clean slate:**

```bash
# 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:**

```bash
# 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](https://github.com/gastownhall/beads/issues/479) were never implemented. Use the workarounds above for a complete reset.

**Related:** [GH#922](https://github.com/gastownhall/beads/issues/922)

### Database corruption

**Important**: Distinguish between **logical consistency issues** (ID collisions, wrong prefixes) and **physical database corruption**.

For **physical database corruption** (disk failures, power loss, filesystem errors):

```bash
# 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):

```bash
# This is NOT corruption - use Dolt merge or bd doctor --fix
bd doctor --fix
```

See [FAQ](FAQ.md#whats-the-difference-between-database-corruption-and-id-collisions) for the distinction.

### Multiple databases detected warning

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:**
- Can cause confusion about which database contains your work
- Easy to accidentally work in the wrong database
- May lead to duplicate tracking of the same work

**Solutions:**

1. **If you have nested projects** (intentional):
   - This is fine! bd is designed to support this
   - Just be aware which database you're using
   - Set `BEADS_DIR` environment variable to point to your `.beads` directory if you want to override the default selection
   - Or use `BEADS_DB` (deprecated) to point directly to the database file

2. **If you have accidental duplicates** (unintentional):
   - Decide which database to keep
   - Export issues from the unwanted database: `cd <unwanted-dir> && bd export -o backup.jsonl`
   - Remove the unwanted `.beads` directory: `rm -rf <unwanted-dir>/.beads`
   - Optionally import issues into the main database if needed

3. **Override database selection**:
   ```bash
   # 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 `▶`).

### Circuit breaker: "server appears down, failing fast"

**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:**

```bash
# 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:**

```bash
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.

### Connection failures after upgrading from pre-Dolt versions

**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:**

1. If you have existing JSONL data from before v0.50, migrate it using the provided script:
   ```bash
   scripts/migrate-jsonl-to-dolt.sh
   ```
2. Start the Dolt server:
   ```bash
   bd dolt start
   ```
3. If the circuit breaker tripped during failed connection attempts, clear the state file (see [Circuit breaker: "server appears down, failing fast"](#circuit-breaker-server-appears-down-failing-fast) above).
4. Verify everything is working:
   ```bash
   bd list
   ```

## Git and Sync Issues

### Merge conflicts

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:

```bash
# 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](ADVANCED.md#handling-git-merge-conflicts) for details.

### Hook timeout kills chained pre-commit hooks

**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:

```bash
# 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.

### Permission denied on git hooks

Git hooks need execute permissions:

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

### "Branch already checked out" when switching branches

**Symptom:**
```bash
$ 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:**
```bash
# 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):**
```bash
bd config set sync.branch ""
```

See [WORKTREES.md#beads-created-worktrees-sync-branch](WORKTREES.md#beads-created-worktrees-sync-branch) for details.

### Unexpected worktree directories in .git/

**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:**
```bash
# 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](WORKTREES.md) for details on how beads uses worktrees.

### Dolt remote sync not working

Check if Dolt server is running and configured:

```bash
# 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
```

## Ready Work and Dependencies

### `bd ready` shows nothing but I have open issues

Those issues probably have open blockers. Check:

```bash
# 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.

### Circular dependency errors

bd prevents dependency cycles, which break ready work detection. To fix:

```bash
# Detect all cycles
bd dep cycles

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

# Or redesign your dependency structure
```

### Dependencies not showing up

Check the dependency type:

```bash
# 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 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):

```bash
# 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.

### Commands are slow

Check database size and consider compaction:

```bash
# 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:
```bash
cd ~/project/component1 && bd init --prefix comp1
cd ~/project/component2 && bd init --prefix comp2
```

## Agent-Specific Issues

### Agent creates duplicate issues

Agents may not realize an issue already exists. 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: `bd list | sort`
- Use `bd merge` to consolidate duplicates: `bd merge bd-2 --into bd-1`

### Agent gets confused by complex dependencies

Simplify the dependency structure:

```bash
# 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
```

### Agent can't find ready work

Check if issues are blocked:

```bash
# 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>
```

### MCP server not working

Check installation and configuration:

```bash
# 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](../integrations/beads-mcp/README.md) for MCP-specific troubleshooting.

### Sandboxed environments (Codex, Claude Code, etc.)

**Issue:** Sandboxed environments restrict permissions, preventing server control and causing "out of sync" errors.

**Common symptoms:**
- "Database out of sync" errors that persist after running `bd dolt pull`
- `bd dolt stop` fails with "operation not permitted"
- Hash mismatch warnings (bd-160)

**Root cause:** The sandbox can't signal/kill the existing Dolt server process.

---

#### Quick fix: Sandbox mode (auto-detected)

**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):

```bash
# Explicitly enable sandbox mode
bd --sandbox ready
bd --sandbox create "Fix bug" -p 1
bd --sandbox update bd-42 --claim
```

**What sandbox mode does:**
- Uses embedded database mode (no server needed)
- Disables auto-export
- Disables auto-import
- Allows bd to work in network-restricted environments

**Note:** You'll need to manually sync when outside the sandbox:
```bash
# After leaving sandbox, sync manually
bd dolt push
```

---

#### Escape hatches for stuck states

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:

```bash
# 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)**

```bash
# Most reliable for sandboxed environments
bd --sandbox ready
bd --sandbox dolt pull
```

---

#### Troubleshooting workflow

If stuck in a sandboxed environment:

```bash
# 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
```

---

#### Understanding the flags

| Flag | Purpose | When to use | Risk |
|------|---------|-------------|------|
| `--sandbox` | Use embedded mode, disable Dolt auto-push | Sandboxed environments (Codex, containers) | Low - safe for sandboxes |
| `bd doctor --fix` | Force metadata update | Stuck staleness loop | Low - updates metadata only |

**Related:**
- See [Claude Code sandboxing documentation](https://www.anthropic.com/engineering/claude-code-sandboxing) for more about sandbox restrictions
- GitHub issue [#353](https://github.com/gastownhall/beads/issues/353) for background

## Platform-Specific Issues

### Windows: Path issues

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

### Windows: Firewall blocking Dolt server

The Dolt server listens on loopback TCP. Allow `bd.exe` through Windows Firewall:

1. Open Windows Security → Firewall & network protection
2. Click "Allow an app through firewall"
3. Add `bd.exe` and enable for Private networks
4. Or disable firewall temporarily for testing

### Windows: Controlled Folder Access blocks bd init

**Symptom:** `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:
```pwsh
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:

1. Open Windows Security → Virus & threat protection
2. Click "Ransomware protection" → "Manage ransomware protection"
3. Under "Controlled folder access", click "Allow an app through Controlled folder access"
4. Click "Add an allowed app" → "Browse all apps"
5. Navigate to and select `bd.exe` (typically in `%USERPROFILE%\go\bin\bd.exe`)
6. Retry `bd init` - it should work instantly

**Note:** 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.

### macOS: Gatekeeper blocking execution

If macOS blocks bd:

1. Verify the downloaded binary checksum matches the release `checksums.txt`.
2. If you used `scripts/install.sh`, note that macOS ad-hoc re-signing is now **opt-in** (`BEADS_INSTALL_RESIGN_MACOS=1`).
3. Use one of the approval paths below.

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

# Or allow in System Preferences
# System Preferences → Security & Privacy → General → "Allow anyway"
```

### Linux: Permission denied

If you get permission errors:

```bash
# 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](https://github.com/gastownhall/beads/issues)
2. **Enable debug logging**: `bd --verbose <command>`
3. **File a bug report**: Include:
   - bd version: `bd version`
   - OS and architecture: `uname -a`
   - Error message and full command
   - Steps to reproduce
4. **Join discussions**: [GitHub Discussions](https://github.com/gastownhall/beads/discussions)

## Related Documentation

- **[README.md](../README.md)** - Core features and quick start
- **[ADVANCED.md](ADVANCED.md)** - Advanced features
- **[FAQ.md](FAQ.md)** - Frequently asked questions
- **[INSTALLING.md](INSTALLING.md)** - Installation guide