- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
website docs, plugin/npm docs, examples, and doctor hints.
- Standardized on:
- CGO_ENABLED=0 go install ... for server-mode only
- CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
capable
- Added scripts/check-go-install-guidance.sh and wired it into CI.
- Updated default.nix to use gms_pure_go instead of ICU flags.
Validation passed locally:
- make test
- golangci-lint run --build-tags=gms_pure_go ./...
- ./scripts/check-go-install-guidance.sh
- ./scripts/check-build-tags.sh
- go test -tags gms_pure_go ./cmd/bd/doctor
- doc flag check
1057 lines
33 KiB
Markdown
1057 lines
33 KiB
Markdown
# 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.
|
||
|
||
### Auto-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 auto-sync | 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
|