What causes "dolt CLI not found (required for remote bootstrap): %w" in gastownhall/beads?

Install the Dolt CLI (e.g. `brew install dolt` or download the release binary) and confirm with `dolt version`.

dolt CLI not found (required for remote bootstrap): %w

Error message

dolt CLI not found (required for remote bootstrap): %w

What it means

Before cloning, bootstrap verifies the `dolt` CLI binary is on PATH via exec.LookPath, because remote bootstrap shells out to `dolt clone`. This error means the Dolt CLI is not installed or not reachable in the current environment, so a cold-start clone cannot proceed.

Source

Thrown at internal/storage/dolt/bootstrap.go:64

// callers should use cfg.GetDoltDatabase() which applies the fallback chain
// (env var → config → default).
func BootstrapFromRemoteWithDB(ctx context.Context, doltDir, remoteURL, database string) (bool, error) {
	// Skip if Dolt database already exists
	if doltExists(doltDir) {
		return false, nil
	}

	if err := remotecache.ValidateRemoteURL(remoteURL); err != nil {
		return false, fmt.Errorf("invalid remote URL: %w", err)
	}

	if err := ValidateDatabaseName(database); err != nil {
		return false, fmt.Errorf("invalid database name %q (use cfg.GetDoltDatabase() to resolve the configured name): %w", database, err)
	}

	// Verify dolt CLI is available
	if _, err := exec.LookPath("dolt"); err != nil {
		return false, fmt.Errorf("dolt CLI not found (required for remote bootstrap): %w", err)
	}

	// Create the parent dolt directory
	if err := os.MkdirAll(doltDir, 0o750); err != nil {
		return false, fmt.Errorf("failed to create dolt directory: %w", err)
	}

	// Clone into <doltDir>/<database>/ so the embedded driver can find it.
	// `dolt clone <url> <target>` creates <target>/.dolt/ directly.
	cloneTarget := filepath.Join(doltDir, database)
	// Record whether the target already existed before this clone attempt.
	// If it did, the failed-clone cleanup below must never touch it: it
	// wasn't created by us, so it could be a pre-existing Dolt repo (e.g.
	// from an earlier bootstrap that a stale/empty doltExists() check
	// missed) that we must not delete.
	targetPreExisted := pathExists(cloneTarget)
	cmd := bootstrapCloneCmd(ctx, remoteURL, cloneTarget)
	if output, err := cmd.CombinedOutput(); err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

Install the Dolt CLI (e.g. `brew install dolt` or download the release binary) and confirm with `dolt version`.
If Dolt is already installed, fix PATH so its directory is included in the environment running bd (check systemd units, cron, and CI containers which use minimal PATHs).
In Docker, add Dolt to the image: copy the binary into /usr/local/bin/ in the Dockerfile.
Alternatively, restore a local .beads/dolt/ directory (e.g. via `bd dolt pull` from another machine) so remote bootstrap is skipped entirely.

Example fix

# before: bootstrap fails in CI because dolt is missing
- run: bd bootstrap
# after: install dolt first
- run: |
    curl -L https://github.com/dolthub/dolt/releases/latest/download/dolt-linux-amd64.tar.gz | tar -xz
    install dolt-linux-amd64/bin/dolt /usr/local/bin/dolt
- run: bd bootstrap

Defensive patterns

Strategy: validation

Validate before calling

if _, err := exec.LookPath("dolt"); err != nil {
    return fmt.Errorf("install dolt before running bd bootstrap: %w", err)
}

Try / catch

ok, err := dolt.BootstrapFromRemote(ctx, doltDir, remote)
if err != nil && strings.Contains(err.Error(), "dolt CLI not found") {
    return fmt.Errorf("install dolt (https://docs.dolthub.com) and ensure it is on PATH: %w", err)
}

Prevention

Add a dolt presence check (exec.LookPath) to setup scripts and CI pre-flight steps.
Bake dolt into Docker images used to run bd.
In services/cron, set PATH explicitly to include the dolt install directory.

When it happens

Trigger: BootstrapFromRemoteWithDB runs (no local .beads/dolt/ exists and a remote is configured) while `dolt` is absent from PATH — Dolt not installed, installed outside PATH, or PATH restricted in CI/containers/cron.

Common situations: Fresh machine or CI runner without Dolt installed; Dolt installed via brew in /opt/homebrew/bin but a service runs with a minimal PATH; running inside a Docker image that only ships the bd binary; broken shell profile so PATH additions never load.

Related errors

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