{"record":{"id":"38fd5d447e8904dd","repo":"gastownhall/beads","slug":"dolt-cli-not-found-required-for-remote-bootstrap","errorCode":null,"errorMessage":"dolt CLI not found (required for remote bootstrap): %w","messagePattern":"dolt CLI not found \\(required for remote bootstrap\\): %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/bootstrap.go","lineNumber":64,"sourceCode":"// callers should use cfg.GetDoltDatabase() which applies the fallback chain\n// (env var → config → default).\nfunc BootstrapFromRemoteWithDB(ctx context.Context, doltDir, remoteURL, database string) (bool, error) {\n\t// Skip if Dolt database already exists\n\tif doltExists(doltDir) {\n\t\treturn false, nil\n\t}\n\n\tif err := remotecache.ValidateRemoteURL(remoteURL); err != nil {\n\t\treturn false, fmt.Errorf(\"invalid remote URL: %w\", err)\n\t}\n\n\tif err := ValidateDatabaseName(database); err != nil {\n\t\treturn false, fmt.Errorf(\"invalid database name %q (use cfg.GetDoltDatabase() to resolve the configured name): %w\", database, err)\n\t}\n\n\t// Verify dolt CLI is available\n\tif _, err := exec.LookPath(\"dolt\"); err != nil {\n\t\treturn false, fmt.Errorf(\"dolt CLI not found (required for remote bootstrap): %w\", err)\n\t}\n\n\t// Create the parent dolt directory\n\tif err := os.MkdirAll(doltDir, 0o750); err != nil {\n\t\treturn false, fmt.Errorf(\"failed to create dolt directory: %w\", err)\n\t}\n\n\t// Clone into <doltDir>/<database>/ so the embedded driver can find it.\n\t// `dolt clone <url> <target>` creates <target>/.dolt/ directly.\n\tcloneTarget := filepath.Join(doltDir, database)\n\t// Record whether the target already existed before this clone attempt.\n\t// If it did, the failed-clone cleanup below must never touch it: it\n\t// wasn't created by us, so it could be a pre-existing Dolt repo (e.g.\n\t// from an earlier bootstrap that a stale/empty doltExists() check\n\t// missed) that we must not delete.\n\ttargetPreExisted := pathExists(cloneTarget)\n\tcmd := bootstrapCloneCmd(ctx, remoteURL, cloneTarget)\n\tif output, err := cmd.CombinedOutput(); err != nil {","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/bootstrap.go#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before: bootstrap fails in CI because dolt is missing\n- run: bd bootstrap\n# after: install dolt first\n- run: |\n    curl -L https://github.com/dolthub/dolt/releases/latest/download/dolt-linux-amd64.tar.gz | tar -xz\n    install dolt-linux-amd64/bin/dolt /usr/local/bin/dolt\n- run: bd bootstrap","handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"dolt\"); err != nil {\n    return fmt.Errorf(\"install dolt before running bd bootstrap: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"ok, err := dolt.BootstrapFromRemote(ctx, doltDir, remote)\nif err != nil && strings.Contains(err.Error(), \"dolt CLI not found\") {\n    return fmt.Errorf(\"install dolt (https://docs.dolthub.com) and ensure it is on PATH: %w\", err)\n}","preventionTips":["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."],"tags":["environment","dolt","missing-binary","bootstrap"],"backgroundTag":"command-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}