> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
# 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
```

<Note>
  Disable debug logging after troubleshooting: `unset BD_DEBUG BD_DEBUG_RPC`
</Note>

## Installation Issues

### bd: command not found

bd is not in your PATH. Either:

```bash theme={null}
# 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:**

```bash theme={null}
# Check all bd binaries
which -a bd

# Example conflict:
# /Users/you/go/bin/bd        <- older
# /opt/homebrew/bin/bd        <- newer
```

**Solution:**

```bash theme={null}
# 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
```

<Warning>
  Choose one installation method (Homebrew recommended) and stick with it. Avoid mixing `go install` with package managers.
</Warning>

### Crashes on macOS

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

**Workaround:**

```bash theme={null}
# 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:
   ```bash theme={null}
   # 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/steveyegge/beads/releases)
3. **Report false positive** to your antivirus vendor

<Note>
  For complete instructions, see the [Antivirus Guide](https://github.com/steveyegge/beads/blob/main/docs/ANTIVIRUS.md).
</Note>

## Database Issues

### bd shows 0 issues but database has data

**Symptom:** All `bd` commands return empty results.

**Diagnosis:**

```bash theme={null}
# 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:
   ```bash theme={null}
   rm -rf .beads/dolt/
   ```

### Database is locked

Another bd process is accessing the database.

```bash theme={null}
# 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
```

<Note>
  For high-concurrency scenarios (multiple agents), use Dolt server mode which handles concurrent access natively.
</Note>

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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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

<Warning>
  Distinguish between **logical consistency issues** (ID collisions) and **physical database corruption** (disk failures).
</Warning>

For **physical database corruption**:

```bash theme={null}
# 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**:

```bash theme={null}
# Use doctor --fix
bd doctor --fix
```

## Git and Sync Issues

### Merge conflicts

Dolt handles merge conflicts natively with cell-level merge.

```bash theme={null}
# Check for conflicts after pull
bd dolt pull

# Resolve conflicts if any
bd vc conflicts
```

<Note>
  With hash-based IDs (v0.20.1+), ID collisions don't occur. Different issues get different hash IDs.
</Note>

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

**Symptom:**

```bash theme={null}
$ 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:**

```bash theme={null}
# 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

```bash theme={null}
# 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.

```bash theme={null}
# 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>
```

<Note>
  Only `blocks` dependencies affect ready work.
</Note>

### Circular dependency errors

bd prevents dependency cycles which break ready work detection.

```bash theme={null}
# 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:

```bash theme={null}
# 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):

```bash theme={null}
# 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

```bash theme={null}
# 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 theme={null}
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

```bash theme={null}
# 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+)**

```bash theme={null}
# 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:**

```bash theme={null}
# Force metadata update
bd import --force

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

# Use sandbox mode (preferred)
bd --sandbox ready
```

<Warning>
  Use `--allow-stale` sparingly - you may see incomplete or outdated data.
</Warning>

## Platform-Specific Issues

### Windows: Path issues

```powershell theme={null}
# 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

```bash theme={null}
# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/bd

# Or allow in System Preferences → Security & Privacy
```

### Linux: Permission denied

```bash theme={null}
# 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/steveyegge/beads/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](https://github.com/steveyegge/beads/discussions)