gastownhall/beads · error

bd binary not found in PATH: %w

Error message

bd binary not found in PATH: %w

What it means

getBdBinary locates the bd executable, preferring the current test binary and otherwise falling back to exec.LookPath("bd"). If bd is not installed or not on PATH, this error wraps the LookPath failure and the calling doctor fix (e.g. GitHooks) cannot run.

Source

Thrown at cmd/bd/doctor/fix/common.go:53

		realPath, err := filepath.EvalSymlinks(exe)
		if err == nil {
			exe = realPath
		}

		// Check if we're running as a test binary - this prevents fork bombs
		// when tests call functions that execute bd subcommands
		baseName := filepath.Base(exe)
		if strings.HasSuffix(baseName, ".test") || strings.Contains(baseName, ".test.") {
			return "", ErrTestBinary
		}

		return exe, nil
	}

	// Fallback to PATH lookup with validation
	bdPath, err := exec.LookPath("bd")
	if err != nil {
		return "", fmt.Errorf("bd binary not found in PATH: %w", err)
	}

	return bdPath, nil
}

// validateBeadsWorkspace ensures the path is a valid beads workspace before
// attempting any fix operations. This prevents path traversal attacks.
func validateBeadsWorkspace(path string) error {
	_, err := resolveWorkspaceBeadsDirs(path)
	return err
}

func resolveWorkspaceBeadsDirs(path string) (workspaceBeadsDirs, error) {
	absPath, err := filepath.Abs(path)
	if err != nil {
		return workspaceBeadsDirs{}, fmt.Errorf("invalid path: %w", err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Install bd or add its location to PATH: `export PATH=$PATH:$(go env GOPATH)/bin`.
2. Invoke the repair through the `bd doctor` command itself so the current-binary fallback resolves.
3. Verify with `which bd` / `command -v bd` in the same shell/environment that runs the fix.
4. In CI, install bd explicitly before running doctor-dependent steps.

Example fix

// before
bd doctor   // fails: bd binary not found in PATH
// after
export PATH="$PATH:$(go env GOPATH)/bin"
bd doctor

if _, err := exec.LookPath("bd"); err != nil {
	// bd missing from PATH; install it or extend PATH before calling doctor fixes
}

if err := fix.GitHooks(ctx); err != nil && strings.Contains(err.Error(), "bd binary not found") {
	// fall back to explicit installation or set PATH before retrying
	return fmt.Errorf("install bd or extend PATH: %w", err)
}

When it happens

Trigger: exec.LookPath("bd") fails in getBdBinary (cmd/bd/doctor/fix/common.go:53) — bd not installed, not on PATH, or the current executable fallback did not apply (not running under `bd doctor` directly).

Common situations: bd installed via go install into ~/go/bin that is absent from PATH; using the library API outside the bd binary in tests or scripts; minimal containers/CI images without bd.

Related errors

• unable to determine home directory: %w
• invalid path: %w
• not a git repository
• nix not found in PATH Manual fix: 1. Edit default.nix:
• cannot find git executable: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/5e73ca155ecc16a8. Report an issue: GitHub.