* Accept uutils coreutils timeout in generated hooks
The generated hook selects a timeout helper only when its --version
banner starts with "timeout (GNU coreutils) ". uutils coreutils reports
"timeout (uutils coreutils) " with the same command line and the same
exit 124 on expiry, so hosts that ship it (Ubuntu 25.10+, NixOS with
uutils-coreutils-noprefix) silently fell through to the Perl alarm, or
to the unbounded direct run when Perl is absent. Follow-up from #5522,
tracked in #5541.
- Widen the identity allowlist to uutils; the match stays by banner so
Windows timeout.exe is still never probed (#5503).
- Add a backend-selection case using the GNU stub with the uutils
banner: fails on the old shim (selects gtimeout), passes with the
widening.
- Regenerate the managed sections in the tracked .githooks/* so
TestTrackedManagedHookSectionsMatchGenerator stays green.
- Update the hook-timeout passages in docs/reference/git-integration.md
and troubleshooting.md, which described the probe as GNU-only.
Verified on NixOS with uutils 0.10.0 as /run/current-system/sw/bin/timeout:
with Perl removed from PATH and a bd that hangs, the old shim runs
"without timeout" for the full duration; the new shim expires at
BEADS_HOOK_TIMEOUT and continues.
Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik
* Regenerate tracked .githooks managed sections with make githooks-regen
TestTrackedManagedHookSectionsMatchGenerator holds the managed section in
each tracked .githooks/* byte-equal to the cmd/bd/hooks.go generator, but
nothing regenerated them: after a generator change a contributor had to
splice the new section in by hand, and the failure only dumped both
texts. The v1.2.0 bump reddened main this way (ce20a64bb), and #6561 shipped
its first revision with the five hooks stale.
- BD_UPDATE_GOLDEN=1 makes the test rewrite the section in place, keeping
everything around the markers (the project's own hook logic) untouched.
Same switch the package's events golden already uses.
- `make githooks-regen` wraps it, next to `corpus-regen`.
- The drift failure now names that command.
- The exactly-one-section check runs before any rewrite.
Verified: drifting one byte inside .githooks/pre-push fails the test with
the hint; `make githooks-regen` restores the file to the same blob SHA;
the test is green again.
Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik
* Check the tracked hook shims against real timeout implementations
The Go tests pin the shim's helper selection with scripted stand-ins, so
they can only encode what the author believes each real `timeout` does.
That is where the last two defects lived: uutils prints a banner the
allowlist did not know (#5541), and busybox — which #5541 suggests
adding — exits 143 on expiry rather than 124, so allowlisting it would
turn every deadline into a failed hook and a blocked push.
checks.nix adds a flake check that runs the tracked .githooks/* managed
sections (held equal to the generator by
TestTrackedManagedHookSectionsMatchGenerator) against the binaries
themselves: GNU coreutils, uutils, busybox and toybox `timeout`, each
with and without perl, under dash, bash and busybox ash, for all five
hooks — 150 cases. Expectations come from a model of the contract (the
allowlist as data), so widening it is one line here and the binaries
either agree or they do not.
A fake bd on the shim's restricted PATH blocks on a held-open fifo until
a helper kills it, records the signal and re-raises it, so each case
asserts the backend that ran (TERM from timeout, ALRM from perl's alarm)
and not merely that the shim finished. No clock: a helper that fails to
kill the fake trips the harness's own `timeout 10`. Every case asserts
exit 0, since anything else blocks the user's push. Reading .githooks/*
instead of building bd keeps it at ~1 s and off the Go build's critical
path; CI's test-nix job runs it after its existing help-text smoke test.
Mutation-checked: restoring main's GNU-only sections fails all 30 uutils
cases (15 unbounded, 15 on the perl backend); allowlisting busybox with
a loosened probe fails all 30 busybox cases with hook exit 143.
Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik
* Run the hook-timeout check under the gtimeout candidate name too
The shim probes `timeout` and then `gtimeout`, but the matrix only ever
put a binary named `timeout` on PATH, so the second candidate was never
run against a real implementation. Whether a helper is accepted under
that name depends on what its banner does with argv[0].
Measured: the uutils multicall dispatches on the argv[0] SUFFIX
(src/bin/coreutils.rs, `binary_as_util.ends_with(util)`) and then prints
the canonical utility name — invoked as gtimeout it reports
"timeout (uutils coreutils) 0.8.0" (this flake's nixos-25.11 pin; 0.11.0
identical), which the allowlist accepts. busybox and toybox know no
gtimeout applet and fail the probe outright, rejected as before. GNU is
immune by construction: Homebrew's gtimeout is a separate binary whose
banner is the fixed "timeout (GNU coreutils) 9.11"; nixpkgs' coreutils
is a single-binary multicall that refuses a foreign name ("unknown
program 'gtimeout'"), so it gets no variant here.
Each multicall is now also installed on a case PATH as `gtimeout` ALONE
(`installs`, derived from `implementations`; `backendFor` stays keyed on
the implementation, so the model's claim is "uutils is allowlisted
whatever it is called"). 240 cases on Linux, 80 on darwin (no busybox or
toybox there, and no busybox-ash shell). The shadowed
`out=` inside run_case is `case_out` now: it only survived because every
case is a backgrounded subshell, and a de-backgrounded case would have
died on the final `touch "$out"`.
Mutation-checked: installing the variant as `xtimeout` (a name the shim
never probes) fails exactly the 30 uutils-as-gtimeout cases — 15 with
nothing killing the fake bd, 15 on the perl backend (ALRM) instead of
coreutils; restored, 240 of 240 pass. The busybox/toybox variants cannot
distinguish (their expectation is rejection either way); their weight is
that the probe does not blow up on a foreign name.
* Run the flake checks on main too, by nix flake check; docs wording
pr-risk.yml's test-nix job ran the hook-timeout check on PRs only; the
byte-identical job in main.yml never got the step, so post-merge main
never ran it. Both jobs now run `nix flake check -L`: no hardcoded
`x86_64-linux` (the step beside it, `nix run .#default`, was already
system-agnostic), and a check added to checks.nix runs without a
workflow edit. checks.aarch64-darwin and .x86_64-darwin evaluate.
Measured on ubuntu-latest with a cold Nix store (fork run 35700791032,
this tree, 240 cases): `nix flake check -L` 3.6 s including substitution
of uutils, busybox, toybox, dash and perl; 0.08 s warm — beside the
4 min 9 s the existing `nix run .#default` step spends building bd in
the same job. The 10-minute timeout is not in question.
git-integration.md: on Git for Windows the preferred deadline backend is
"a coreutils timeout (GNU or uutils)", not GNU alone, since both now
qualify. troubleshooting.md: reflow a ragged paragraph.
* review: close the duplicated contracts around the uutils timeout accept
Maintainer review fixes for #6561. No change to the shim's behavior or to the
generated/tracked hook sections.
- cmd/bd/hooks_timeout_process_test.go: the uutils fixture was built with
strings.Replace, which returns its input unchanged when the pattern is
absent, so a later edit to the GNU stub's banner would silently degenerate
the uutils case into a second copy of the GNU one — still green, no longer
testing the new accept. Hoist the derivation and fail loudly when the banner
no longer matches.
- cmd/bd/hooks_timeout_process_test.go: findHookProcessGNUTimeout held a second,
un-widened copy of the identity allowlist, so on exactly the hosts this PR
exists for (uutils timeout, no gtimeout) the only Go test that drives a real
timeout binary skipped with a reason the fix had just made false. Widen the
probe's case, rename it findHookProcessCoreutilsTimeout, and reword the skip
and the subtest. Measured against stub PATHs: uutils goes rc=1 -> rc=0, GNU
stays rc=0, a busybox banner stays rc=1.
- cmd/bd/init_hooks_test.go: TestGenerateHookSection_Timeout asserted only the
GNU alternative, so deleting the new uutils one from the generator left the
structural contract green (verified: it passes under that mutation before
this change, and reports "section missing uutils coreutils identity check"
after). Add the companion assertion.
- cmd/bd/init_hooks_test.go, Makefile: the regen arm rewrites tracked source
files, so give it its own BD_UPDATE_HOOKS_GOLDEN rather than the package's
shared BD_UPDATE_GOLDEN — an unscoped `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/`
used to turn genuine hook drift into a silent working-tree rewrite that
reported PASS.
- cmd/bd/init_hooks_test.go: locate the managed section by marker prefix
instead of the versioned marker line. Tracked hooks drift both from generator
content and from the release version stamp; the exact-line lookup made the
second class fatal ("tracked hook missing ...") before the regen arm was
reachable, so `make githooks-regen` failed at exactly the moment a release
engineer reaches for it. The versioned markers are still verified — they are
part of the byte compare.
- checks.nix: the `rc -eq 124` safety-net verdict discarded both $case_out and
the already-captured $signal, so the one failure mode that is intermittent
and not locally reproducible was also the only one with no diagnostics.
Report them like the `rc -ne 0` branch below it.
- docs/reference/troubleshooting.md, docs/reference/git-integration.md: mirror
the coreutils wording across both docs this PR touches, and generalize the
re-install guidance in both. Managed sections are never reported Outdated
(getHookVersion returns IsShim for them and computeHookStatuses gates on
!IsShim), so nothing tells an existing install it is stale; the sentence was
still scoped to the older name-only check (#5503).
- CHANGELOG.md: add the [Unreleased] entry for #5541, worded to the actual
scope — with Perl installed the shim still reached the Perl alarm arm, so the
lost deadline bit uutils hosts without Perl — say that existing installs must
run `bd hooks install` once, and drop the claim that stock NixOS ships uutils
(this PR's own checks.nix takes GNU from pkgs.coreutils).
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
961 lines
29 KiB
Markdown
961 lines
29 KiB
Markdown
---
|
|
title: Troubleshooting
|
|
description: Fixes for common bd problems across installation, the database and Dolt server, sync, git hooks, dependencies, and platform-specific issues.
|
|
---
|
|
|
|
Common issues and solutions. For step-by-step runbooks, see the
|
|
[Recovery section](/recovery/index).
|
|
|
|
## Installation Issues
|
|
|
|
### `bd: command not found`
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### Wrong version of bd running
|
|
|
|
If `bd version` shows an unexpected version (e.g., older than what you just
|
|
installed), you likely have multiple `bd` binaries in your PATH:
|
|
|
|
```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
|
|
```
|
|
|
|
This happens when a binary from an earlier `go install` sits in `~/go/bin/`
|
|
ahead of a newer package-manager install. Choose one installation method
|
|
(Homebrew recommended) and stick with it.
|
|
|
|
### `zsh: killed bd` on macOS
|
|
|
|
CGO/SQLite compatibility issue:
|
|
|
|
```bash
|
|
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/
|
|
```
|
|
|
|
Homebrew builds already enable CGO, so this shouldn't be necessary there. If
|
|
you still see crashes with the Homebrew version, please
|
|
[file an issue](https://github.com/gastownhall/beads/issues).
|
|
|
|
### Permission denied
|
|
|
|
```bash
|
|
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"
|
|
```
|
|
|
|
### Antivirus flags bd as malware
|
|
|
|
Kaspersky, Windows Defender, and others sometimes flag `bd` as a generic
|
|
trojan. This is a **false positive** — Go binaries commonly trigger antivirus
|
|
heuristics. Verify the binary's SHA256 checksum against the
|
|
[GitHub release page](https://github.com/gastownhall/beads/releases) before
|
|
adding an exclusion. See [Antivirus False Positives](/reference/antivirus) for
|
|
per-vendor instructions.
|
|
|
|
## Database Issues
|
|
|
|
### Database not found
|
|
|
|
```bash
|
|
# Initialize beads
|
|
bd init --quiet
|
|
|
|
# Or point bd at an existing .beads directory
|
|
BEADS_DIR=/path/to/.beads bd list
|
|
```
|
|
|
|
### Database locked
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
<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.
|
|
</Warning>
|
|
|
|
For high-concurrency scenarios (multiple agents), server mode
|
|
(`bd init --server`) handles concurrent access natively via `dolt sql-server`.
|
|
|
|
### `bd init` refuses to run
|
|
|
|
`bd init` and `bd dolt` refuse operations that could destroy local or remote
|
|
history, printing a pattern code such as `init-local-exists` or
|
|
`pk-fork-refused`. Each code has a runbook — see
|
|
[Recovery Playbooks](/recovery/init-safety). Export first
|
|
(`bd export -o backup.jsonl`) if you intend to re-initialize over existing
|
|
data.
|
|
|
|
### Corrupted database
|
|
|
|
Distinguish **logical consistency issues** (ID collisions, wrong prefixes)
|
|
from **physical database corruption** (disk failures, power loss, filesystem
|
|
errors).
|
|
|
|
For logical consistency issues — this is not corruption:
|
|
|
|
```bash
|
|
bd doctor --fix
|
|
```
|
|
|
|
For physical corruption, rebuild from a Dolt remote or a backup:
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
See [Database Corruption](/recovery/database-corruption) for the full runbook.
|
|
|
|
### Dolt journal corruption after restart
|
|
|
|
**Symptom (server mode):** 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
|
|
# 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
|
|
```
|
|
|
|
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.
|
|
|
|
### `failed to import: issue already exists`
|
|
|
|
You're trying to bootstrap a database with issues that conflict with existing
|
|
ones. Clear the local database and re-initialize from an export:
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### Imported children whose parent is gone
|
|
|
|
Bootstrapping from JSONL or pulling hierarchical issues (e.g., `bd-abc.1`) can
|
|
land children whose parent `bd-abc` no longer exists — typically after
|
|
`bd delete` on a parent, a branch merge where one side deleted it, or an
|
|
incomplete import.
|
|
|
|
Import accepts these orphans rather than failing, so the children still arrive
|
|
and stay usable. Recreate the parent (or close out the orphaned children) once
|
|
the import finishes.
|
|
|
|
**Prevention:** use `bd delete --cascade` to also delete children, and review
|
|
children first with `bd children <parent-id>`.
|
|
|
|
### Old data returns after reset
|
|
|
|
`bd admin reset --force` only removes **local** beads data. Old issues can
|
|
return from configured Dolt remotes or from other machines that push after
|
|
you reset. For a complete clean slate, reset every clone (or clear the
|
|
remote's beads data) before re-running `bd init`.
|
|
|
|
If you previously used the removed legacy sync-branch feature, also delete
|
|
its branch and worktrees — see
|
|
[Worktrees: Legacy Cleanup](/reference/worktrees#legacy-cleanup).
|
|
|
|
### `bd` shows 0 issues but the database has data
|
|
|
|
**Symptom (server mode):** All `bd` commands return empty results even though
|
|
your data exists.
|
|
|
|
**Cause:** `bd` is connecting to a different Dolt server or database than
|
|
expected — an empty "shadow" database on the wrong server.
|
|
|
|
**Diagnosis:**
|
|
|
|
```bash
|
|
# 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'
|
|
```
|
|
|
|
**Fix:** ensure your Dolt server is running from the correct data directory
|
|
and that `metadata.json` points at the right server and port. If a stale
|
|
`.beads/dolt/` directory exists alongside an external-server configuration,
|
|
it can shadow the real database — confirm your real data lives on the server
|
|
before removing the stale directory.
|
|
|
|
### Configured server unreachable (auto-start disabled)
|
|
|
|
**Symptom (server mode):** `bd` returns "database not found on Dolt server"
|
|
when the configured server is down.
|
|
|
|
**Cause:** When `metadata.json` has an explicit `dolt_server_port`, bd treats
|
|
the server as externally managed and intentionally disables auto-start —
|
|
spawning 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`.
|
|
|
|
### Port conflicts with multiple projects
|
|
|
|
**Symptom (server mode):** Commands in a second project fail or connect to the
|
|
wrong database, and multiple `dolt sql-server` processes are running.
|
|
|
|
**Cause:** Each server-mode project starts its own Dolt server by default,
|
|
which can conflict on machines with many projects.
|
|
|
|
**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
|
|
bd config set dolt.shared-server true
|
|
```
|
|
|
|
After enabling, existing projects may need `bd init --reinit-local -q` to
|
|
create their database on the shared server.
|
|
|
|
**Verify:** `bd dolt status` from any project should show the same server,
|
|
port 3308, and `~/.beads/shared-server/` as the data directory.
|
|
|
|
### Multiple databases detected warning
|
|
|
|
bd warns when it finds more than one `.beads` directory in your directory
|
|
hierarchy, marking the one in use with `▶` (usually the closest to your
|
|
current directory). Multiple databases risk working in the wrong one or
|
|
tracking the same work twice.
|
|
|
|
- **Nested projects (intentional):** this is supported — just note which
|
|
database is active, or pin it explicitly.
|
|
- **Accidental duplicates:** export from the unwanted database
|
|
(`bd export -o issue-export.jsonl`), then remove its `.beads` directory.
|
|
- **Override selection:**
|
|
|
|
```bash
|
|
# Point bd at a specific .beads directory (recommended)
|
|
export BEADS_DIR=/path/to/.beads
|
|
|
|
# Legacy method (deprecated, points at the database file directly)
|
|
export BEADS_DB=/path/to/db
|
|
```
|
|
|
|
### Circuit breaker: "server appears down, failing fast"
|
|
|
|
**Symptom (server mode):** Every `bd` command fails with
|
|
`dolt circuit breaker is open: server appears down, failing fast (cooldown 30s)`,
|
|
persisting across repeated invocations.
|
|
|
|
**Cause:** The circuit breaker tripped after repeated connection failures.
|
|
Its state lives in a file under `/tmp/beads-circuit/` (named
|
|
`beads-dolt-circuit-<host>-<port>[-<db>].json`, keyed on host:port) and is
|
|
shared across all `bd` processes. Once tripped, all commands to that host:port
|
|
are rejected until a successful probe resets it.
|
|
|
|
For beads-managed local servers, `bd dolt status` reports from the server's
|
|
PID file — a "running" status does not guarantee the server is actually
|
|
accepting connections on the expected port.
|
|
|
|
**Diagnosis:**
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
**Fix:**
|
|
|
|
```bash
|
|
rm /tmp/beads-circuit/beads-dolt-circuit-*.json
|
|
bd dolt stop
|
|
bd dolt start
|
|
bd list
|
|
```
|
|
|
|
On macOS, `/tmp` is a symlink to `/private/tmp`, which is not always cleared
|
|
on restart — the state file can persist across reboots.
|
|
|
|
## Dolt Server Issues
|
|
|
|
### Server not starting
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### Version mismatch
|
|
|
|
After upgrading bd:
|
|
|
|
```bash
|
|
bd dolt stop
|
|
bd dolt start
|
|
```
|
|
|
|
### Proxied-server mode: "dolt is older than the recommended minimum" warning
|
|
|
|
Managed proxied-server mode spawns an external `dolt` CLI it finds via
|
|
`BEADS_DOLT_BIN` or PATH (in that order — see
|
|
[Environment Variables](/reference/configuration#environment-variables); a
|
|
clone-local sidecar setting will slot between the two when the sidecar
|
|
reader lands in contract part 2). On
|
|
startup it probes that binary with `dolt version` and recommends
|
|
**dolt >= 2.0.0**: the 2026-07-25 cross-version compatibility matrix found
|
|
that cross-reading storage written by the beads Dolt Go module (as opposed
|
|
to writing it, which older dolt CLIs can also do) requires dolt >= 2.0.0 —
|
|
dolt 1.85 can *serve* proxied mode but cannot *read* storage the module
|
|
wrote, and dolt 1.52.1 fails at both serving and reading.
|
|
|
|
This is a warning, not a hard failure — there is deliberately no hard
|
|
version floor, so an older dolt can still be used at your own risk. To
|
|
resolve it, install the pinned dolt version — see
|
|
[Which Dolt version to install](/architecture/dolt#which-dolt-version-to-install)
|
|
— and either update PATH or set `BEADS_DOLT_BIN` to the new binary's path.
|
|
Install that specific version rather than `latest`: 2.3.x is a newer release
|
|
that satisfies this warning but carries a
|
|
[separate data-operation defect](/architecture/dolt#which-dolt-version-to-install).
|
|
|
|
The advisory repeats at most once per day, not on every command: the probe
|
|
result and the warning timestamp are cached (keyed by the binary's path,
|
|
size, and mtime, in the user cache directory), so day-to-day `bd` use stays
|
|
quiet while the reminder still resurfaces until the binary is upgraded.
|
|
Upgrading or replacing the dolt binary re-probes immediately.
|
|
|
|
If the probe can't parse `dolt version`'s output at all (most commonly a
|
|
dev/custom build with non-standard version output), that also only warns —
|
|
proxied-server mode still starts, since an unparseable version means "we
|
|
don't know", not "this is definitely broken". A genuinely missing or
|
|
broken `dolt` binary (not found, not executable, or the probe itself
|
|
fails/times out) is a hard error, not a warning.
|
|
|
|
### Proxied-server mode: closing a bead gate fails with "no local store available"
|
|
|
|
```
|
|
gate condition not satisfied: bead gate "bd-a1b2": no local store available (use --force to override)
|
|
```
|
|
|
|
`bd close` on a bead gate refuses this way in proxied-server mode even when
|
|
the awaited bead is closed. Proxied-server commands run against a shared
|
|
`dolt sql-server` and never open a local store, so the close path has
|
|
nothing to read the awaited bead's status from.
|
|
|
|
`bd gate check` does evaluate bead gates in proxied-server mode, and closes
|
|
the ones whose target has closed:
|
|
|
|
```bash
|
|
bd gate check --type=bead # closes bead gates whose awaited bead is closed
|
|
bd close <gate-id> --force # or close without verifying the condition
|
|
```
|
|
|
|
Tracked in [#5861](https://github.com/gastownhall/beads/issues/5861).
|
|
|
|
### Prefix routing: "proxy server store needs to be uow provider"
|
|
|
|
A lookup routed through the orchestrator's `routes.jsonl` prefix routes
|
|
fails with this error when the rig that owns the prefix is itself running in
|
|
proxied-server mode — routed reads cannot open a proxied-server rig. In an
|
|
all-proxied shared-server topology that applies to every routed target, so
|
|
cross-rig bead gates and a plain `bd show <routed-id>` both dead-end here.
|
|
|
|
Run the command from the owning rig's own workspace instead, where the ID
|
|
resolves locally rather than through a route. Tracked in
|
|
[#5861](https://github.com/gastownhall/beads/issues/5861).
|
|
|
|
## Sync Issues
|
|
|
|
### Changes not syncing
|
|
|
|
```bash
|
|
# Force push to Dolt remote
|
|
bd dolt push
|
|
|
|
# Check hooks
|
|
bd hooks list
|
|
```
|
|
|
|
### Recovery from backup
|
|
|
|
```bash
|
|
# Restore from a Dolt backup
|
|
bd backup restore [path] --force
|
|
|
|
# Or pull from Dolt remote
|
|
bd dolt pull
|
|
```
|
|
|
|
### Merge conflicts
|
|
|
|
Dolt merges at the cell level, so concurrent changes conflict only when they
|
|
touch the same field of the same issue. Hash-based IDs mean different issues
|
|
never collide on ID.
|
|
|
|
```bash
|
|
# Check for and fix Dolt conflicts
|
|
bd doctor --fix
|
|
|
|
# Re-push
|
|
bd dolt push
|
|
```
|
|
|
|
See [Merge Conflicts](/recovery/merge-conflicts) for the full runbook.
|
|
|
|
## Git Hook Issues
|
|
|
|
### Hooks not running
|
|
|
|
```bash
|
|
# Check if installed
|
|
ls -la .git/hooks/
|
|
|
|
# Reinstall
|
|
bd hooks install
|
|
```
|
|
|
|
### Hook errors
|
|
|
|
```bash
|
|
# Check hook script
|
|
cat .git/hooks/pre-commit
|
|
|
|
# Run manually
|
|
.git/hooks/pre-commit
|
|
```
|
|
|
|
### Hook timeout kills chained pre-commit hooks
|
|
|
|
**Symptom:** After `bd hooks install`, chained pre-commit hooks (eslint,
|
|
prettier, ruff, etc.) stop running, with:
|
|
`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 internally, the timeout
|
|
covers both beads' own work and your entire hook pipeline.
|
|
|
|
**Fix:** Increase the timeout (default 300 seconds):
|
|
|
|
```bash
|
|
# Add to ~/.bashrc or ~/.zshrc
|
|
export BEADS_HOOK_TIMEOUT=600 # 10 minutes (in seconds)
|
|
```
|
|
|
|
The value must be a positive whole number of seconds. Invalid values and zero
|
|
warn and fall back to 300 seconds. Beads accepts `timeout` or `gtimeout` only
|
|
when a successful version probe identifies GNU coreutils or uutils coreutils;
|
|
native Windows `timeout.exe` is not compatible. If neither a coreutils timeout
|
|
nor Perl is available, the hook warns that it is running directly without a
|
|
deadline.
|
|
|
|
The coreutils helper sends `TERM`; on POSIX hosts, Perl's alarm applies to the
|
|
direct `bd` process. Git for Windows Perl does not guarantee that alarm across
|
|
`exec`, so a coreutils `timeout` (GNU or uutils) is preferred there.
|
|
TERM-resistant work and descendant processes are not guaranteed to stop.
|
|
|
|
Already-installed hook sections are not refreshed automatically. After upgrading
|
|
to a version that changed the timeout probe — the name-only check, or the uutils
|
|
coreutils banner — run `bd hooks install` once to refresh existing canonical
|
|
sections.
|
|
|
|
### 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
|
|
```
|
|
|
|
### Corrupted symlinked `CLAUDE.md`
|
|
|
|
**Symptom:** Git reports `CLAUDE.md` as a symlink entry (mode `120000`), but
|
|
the indexed blob contains multi-line Markdown instead of a one-line symlink
|
|
target. On macOS this can make clones or checkouts fail.
|
|
|
|
This affects repositories corrupted by older setup behavior (fixed in
|
|
[#4192](https://github.com/gastownhall/beads/pull/4192)). To repair an
|
|
existing bad index entry:
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
Commit the mode repair after review.
|
|
|
|
### "Branch already checked out" or unexpected `.git/beads-worktrees/`
|
|
|
|
Older beads versions created hidden git worktrees for a removed sync-branch
|
|
feature; leftovers can lock branches (`fatal: 'main' is already checked out
|
|
at .../beads-worktrees/...`). Remove them:
|
|
|
|
```bash
|
|
rm -rf .git/beads-worktrees
|
|
rm -rf .git/worktrees/beads-*
|
|
git worktree prune
|
|
```
|
|
|
|
See [Worktrees: Legacy Cleanup](/reference/worktrees#legacy-cleanup).
|
|
|
|
## Dependency Issues
|
|
|
|
### `bd ready` shows nothing but I have open issues
|
|
|
|
Those issues probably have open blockers:
|
|
|
|
```bash
|
|
# 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>
|
|
```
|
|
|
|
Remember: only `blocks` dependencies affect ready work.
|
|
|
|
### Circular dependencies
|
|
|
|
bd prevents dependency cycles, which break ready work detection:
|
|
|
|
```bash
|
|
# Detect cycles
|
|
bd dep cycles
|
|
|
|
# Remove one dependency
|
|
bd dep remove bd-A bd-B
|
|
```
|
|
|
|
See [Circular Dependencies](/recovery/circular-dependencies) for the full
|
|
runbook.
|
|
|
|
### Dependencies not showing up
|
|
|
|
```bash
|
|
# Show full issue details including dependencies
|
|
bd show <issue-id>
|
|
|
|
# Visualize the dependency tree
|
|
bd dep tree <issue-id>
|
|
```
|
|
|
|
Different dependency types have different meanings — only `blocks` gates
|
|
ready work. See [Dependencies](/core-concepts/dependencies).
|
|
|
|
## Performance Issues
|
|
|
|
### Slow queries
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
Consider splitting very large projects into multiple databases:
|
|
|
|
```bash
|
|
cd ~/project/component1 && bd init --prefix comp1
|
|
cd ~/project/component2 && bd init --prefix comp2
|
|
```
|
|
|
|
### High memory usage
|
|
|
|
```bash
|
|
# Run Dolt garbage collection to compact storage
|
|
bd admin compact --dolt
|
|
```
|
|
|
|
If this or `bd flatten` stops with `Error 1105 (HY000): context canceled`,
|
|
see [Storage reclaim fails with "context canceled"](#storage-reclaim-fails-with-context-canceled)
|
|
below.
|
|
|
|
### Storage reclaim fails with "context canceled"
|
|
|
|
`bd flatten` and the Dolt-history compaction in `bd admin compact` finish by
|
|
hard-resetting `main` onto a temporary branch; the merge-settle path behind
|
|
`bd dolt pull` / `bd sync` falls back to a hard reset when it abandons a
|
|
merge. On Dolt 2.3.x a few percent of freshly created databases come up with
|
|
`CALL DOLT_RESET('--hard')` broken for the life of the server process, so on
|
|
an affected database those commands stop with:
|
|
|
|
```
|
|
Error 1105 (HY000): context canceled
|
|
```
|
|
|
|
Nothing else looks wrong — ordinary queries, commits, soft resets,
|
|
`CALL DOLT_CLEAN()` and `CALL DOLT_CHECKOUT('.')` all still work — so the
|
|
problem only shows up when something needs a hard reset. Confirm with the
|
|
check in
|
|
[Which Dolt version to install](/architecture/dolt#which-dolt-version-to-install),
|
|
which also covers the fix: restarting `dolt sql-server` clears it for now,
|
|
and installing the pinned Dolt version keeps it clear.
|
|
|
|
This applies to server and proxied-server mode, which use the standalone
|
|
`dolt` CLI. Embedded mode links its own Dolt engine at the version pinned in
|
|
`go.mod` and is not affected by which `dolt` CLI is on your PATH.
|
|
|
|
## Agent Issues
|
|
|
|
### Agent creates duplicate issues
|
|
|
|
Agents may not realize an issue already exists. Prevention strategies:
|
|
|
|
- Have agents search first: `bd list --json | grep "title"`
|
|
- Label auto-created issues: `bd create "..." -l auto-generated`
|
|
- Consolidate duplicates: `bd duplicate <dup-id> --of <canonical-id>` closes
|
|
the duplicate with a reference to the canonical issue
|
|
|
|
### 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
|
|
```
|
|
|
|
### MCP server not working
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
See [MCP Server](/integrations/mcp-server) for setup and configuration.
|
|
|
|
### Sandboxed environments (Codex, Claude Code, etc.)
|
|
|
|
Sandboxes that restrict process and network permissions can prevent bd from
|
|
controlling a Dolt server, causing persistent "database out of sync" errors
|
|
or `bd dolt stop` failing with "operation not permitted".
|
|
|
|
bd auto-detects sandboxed environments and prints
|
|
`Sandbox detected, using direct mode`. If auto-detection fails, pass the
|
|
global `--sandbox` flag explicitly:
|
|
|
|
```bash
|
|
bd --sandbox ready
|
|
bd --sandbox create "Fix bug" -p 1
|
|
```
|
|
|
|
Sandbox mode disables Dolt auto-push so bd works without server control or
|
|
network access. Sync manually once outside the sandbox:
|
|
|
|
```bash
|
|
bd dolt push
|
|
```
|
|
|
|
If staleness errors persist, `bd doctor --fix` forces a metadata refresh
|
|
(low risk — it updates tracking metadata, not issues). Background:
|
|
[GH#353](https://github.com/gastownhall/beads/issues/353).
|
|
|
|
## 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 the Dolt server
|
|
|
|
In server mode, the Dolt server listens on loopback TCP. Allow `bd.exe`
|
|
through Windows Firewall: Windows Security → Firewall & network protection →
|
|
"Allow an app through firewall" → add `bd.exe` for Private networks.
|
|
|
|
### Windows: Controlled Folder Access blocks `bd init`
|
|
|
|
**Symptom:** `bd init` hangs indefinitely with high CPU usage, and CTRL+C
|
|
doesn't work. Controlled Folder Access may block bd without showing a
|
|
notification, making this hard to diagnose without the `-v` flag:
|
|
|
|
```pwsh
|
|
bd init -v
|
|
# Error: failed to create .beads directory: mkdir .beads: The system cannot find the file specified
|
|
```
|
|
|
|
**Solution:** Whitelist `bd.exe`: Windows Security → Virus & threat
|
|
protection → Ransomware protection → Controlled folder access → "Allow an
|
|
app through Controlled folder access" → browse to `bd.exe` (typically
|
|
`%USERPROFILE%\go\bin\bd.exe`). Then retry `bd init`.
|
|
|
|
### Windows: `ENOENT` when a Node program spawns `bd`
|
|
|
|
**Symptom:** An editor extension, MCP server, or script that shells out to
|
|
`bd` fails on Windows with `spawn bd ENOENT`, even though `bd` runs fine in
|
|
the same terminal.
|
|
|
|
The npm package installs `bd` as a generated `bd.cmd` shim, not as an
|
|
executable named `bd`. Node's `execFile()` and `spawn()` run their target
|
|
directly instead of through a shell, so they never apply the `PATHEXT`
|
|
resolution that finds `bd.cmd` — and a batch file is not directly executable
|
|
in the first place.
|
|
|
|
**Solution:** Name the shim explicitly and give it a shell:
|
|
|
|
```js
|
|
const { execFile } = require('node:child_process');
|
|
|
|
const isWindows = process.platform === 'win32';
|
|
|
|
execFile(
|
|
isWindows ? 'bd.cmd' : 'bd',
|
|
['ready', '--json'],
|
|
{ shell: isWindows },
|
|
(err, stdout) => { /* ... */ },
|
|
);
|
|
```
|
|
|
|
To avoid a shell — and the argument quoting that comes with it — spawn the
|
|
native binary the shim wraps, at `node_modules/@beads/bd/bin/bd.exe`.
|
|
|
|
### Windows: `/tmp` paths silently land in the drive root
|
|
|
|
**Symptom:** A `bd` command given a `/tmp/...` path reports success, but
|
|
the file is not where you look for it — it was written to `C:\tmp\...`.
|
|
|
|
`bd.exe` is a native Windows binary and does not share Git Bash's emulated
|
|
POSIX filesystem. When a literal `/tmp/...` string reaches `bd`, it resolves
|
|
against the current drive root.
|
|
|
|
In a default interactive Git Bash this usually does *not* happen — Git for
|
|
Windows converts standalone POSIX-path arguments to Windows paths before
|
|
`bd.exe` sees them. The trap appears when that conversion is out of play:
|
|
|
|
- `MSYS_NO_PATHCONV=1` or `MSYS2_ARG_CONV_EXCL` is set (common in
|
|
Docker-heavy environments)
|
|
- the path comes from a config value or a file, not a command-line argument
|
|
- `bd` is spawned by a non-MSYS parent — a Node script, editor extension,
|
|
or MCP server — which passes the string through verbatim:
|
|
|
|
```js
|
|
// 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
|
|
```
|
|
|
|
**Solution:** Hand `bd` a Windows path — `os.tmpdir()` from Node,
|
|
`"$(cygpath -w /tmp)\issues.jsonl"` from Git Bash scripts. This applies to
|
|
any path argument, including `--db` and config values.
|
|
|
|
### macOS: Gatekeeper blocking execution
|
|
|
|
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
|
|
opt-in (`BEADS_INSTALL_RESIGN_MACOS=1`).
|
|
3. Approve the binary:
|
|
|
|
```bash
|
|
# Remove quarantine attribute
|
|
xattr -d com.apple.quarantine /usr/local/bin/bd
|
|
|
|
# Or: System Preferences → Security & Privacy → General → "Allow anyway"
|
|
```
|
|
|
|
## Debug Environment Variables
|
|
|
|
bd supports environment variables for debugging specific subsystems. Enable
|
|
them when troubleshooting or when requested by maintainers.
|
|
|
|
| Variable | Purpose | Output |
|
|
|----------|---------|--------|
|
|
| `BD_DEBUG` | General debug logging | stderr |
|
|
| `BD_DEBUG_RPC` | RPC communication between CLI and Dolt server | stderr |
|
|
| `BD_DEBUG_SYNC` | Sync and import timestamp protection | stderr |
|
|
| `BD_DEBUG_ROUTING` | Issue routing and multi-repo resolution | stderr |
|
|
| `BD_DEBUG_FRESHNESS` | Database file replacement detection | server log |
|
|
|
|
Set any of them to `1` to enable; `unset` to disable.
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
For multi-repo routing configuration, see [Routing](/multi-agent/routing).
|
|
|
|
## Getting Help
|
|
|
|
### Debug output
|
|
|
|
```bash
|
|
bd --verbose list
|
|
```
|
|
|
|
### Logs
|
|
|
|
```bash
|
|
# Server mode (embedded mode runs in-process, no server log)
|
|
cat .beads/dolt-server.log
|
|
```
|
|
|
|
### System info
|
|
|
|
```bash
|
|
bd info --json
|
|
```
|
|
|
|
### File an issue
|
|
|
|
```bash
|
|
# Include this info
|
|
bd version
|
|
bd info --json
|
|
uname -a
|
|
```
|
|
|
|
Report at: https://github.com/gastownhall/beads/issues — or ask in
|
|
[GitHub Discussions](https://github.com/gastownhall/beads/discussions).
|