gastownhall/beads · error

dolt binary not found

Error message

dolt binary not found

What it means

ErrNotFound is the canonical sentinel from internal/doltversion meaning no candidate dolt binary could be located at all: an explicit path (BEADS_DOLT_BIN env var or sidecar path) did not exist, or exec.LookPath found nothing named dolt on PATH. Resolve/Probe wrap it with %w, so callers branch with errors.Is instead of parsing message text (e.g. to print an install hint vs a config hint).

Source

Thrown at internal/doltversion/errors.go:14

package doltversion

import "errors"

// Canonical error sentinels for this package. All errors returned by
// Resolve/Probe/ProbeWithPolicy wrap one of these with %w, so callers can
// use errors.Is to branch on failure category (e.g. to decide whether to
// print an install hint vs a "check your BEADS_DOLT_BIN setting" hint)
// without parsing message text.
var (
	// ErrNotFound means no candidate dolt binary could be located at all:
	// an explicit env/sidecar path did not exist, or exec.LookPath found
	// nothing on PATH.
	ErrNotFound = errors.New("dolt binary not found")

	// ErrNotExecutable means a candidate path exists but is not usable as
	// an executable: it is a directory, or it is a regular file lacking
	// the executable bit. This is distinct from ErrNotFound because the
	// remediation is different — the path is real, but the file itself is
	// wrong (wrong permissions, wrong kind of file), which is more likely
	// a misconfiguration than a missing install.
	ErrNotExecutable = errors.New("dolt path is not executable")

	// ErrProbeFailed covers everything that can go wrong actually running
	// `<path> version`: the exec call itself failing (including exec
	// format errors from architecture/loader mismatches), the process
	// timing out, or the process exiting non-zero. These are grouped
	// together because callers generally respond to all of them the same
	// way (probe failed, do not proceed) even though the underlying causes
	// differ; the wrapped error's message still carries the specific cause.
	ErrProbeFailed = errors.New("dolt version probe failed")

View on GitHub (pinned to 71377f2769)

Solutions

1. Install Dolt (e.g. `brew install dolt` or download from dolthub) so `dolt` is on PATH
2. If BEADS_DOLT_BIN is set, verify the path exists and correct it (`ls $(BEADS_DOLT_BIN)`), or unset it to fall back to PATH lookup
3. Fix PATH in the execution environment (systemd unit, cron, CI) so the dolt install location is included

Example fix

// before
export BEADS_DOLT_BIN=/usr/local/bin/doltt
// after
export BEADS_DOLT_BIN=/usr/local/bin/dolt  # verify with: test -x "$BEADS_DOLT_BIN"

p := os.Getenv("BEADS_DOLT_BIN")
if p != "" {
    if _, err := os.Stat(p); err != nil {
        return fmt.Errorf("BEADS_DOLT_BIN does not exist: %s", p)
    }
} else if _, err := exec.LookPath("dolt"); err != nil {
    return fmt.Errorf("dolt not installed or not on PATH")
}

func IsDoltNotFound(err error) bool {
    return errors.Is(err, doltversion.ErrNotFound)
}

if _, err := doltversion.Resolve(); err != nil {
    if errors.Is(err, doltversion.ErrNotFound) {
        // print install hint (or "check BEADS_DOLT_BIN" if env var was set)
    }
    return err
}

When it happens

Trigger: Calling doltversion.Resolve or doltversion.Probe when (1) BEADS_DOLT_BIN points to a nonexistent file, (2) the bundled sidecar path does not exist, or (3) dolt is not installed / not on PATH and LookPath("dolt") fails.

Common situations: Fresh machine or CI container without Dolt installed; BEADS_DOLT_BIN set to a typo'd or deleted path; PATH stripped in systemd/cron environments so the binary installed via Homebrew isn't visible.

Related errors

• ErrNotFound
• dolt directory is required
• dolt path is not executable
• dolt version probe failed
• dolt version output is unparseable

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