{"record":{"id":"ffeee8fbaf281c4d","repo":"gastownhall/beads","slug":"dolt-binary-not-found","errorCode":null,"errorMessage":"dolt binary not found","messagePattern":"dolt binary not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltversion/errors.go","lineNumber":14,"sourceCode":"package doltversion\n\nimport \"errors\"\n\n// Canonical error sentinels for this package. All errors returned by\n// Resolve/Probe/ProbeWithPolicy wrap one of these with %w, so callers can\n// use errors.Is to branch on failure category (e.g. to decide whether to\n// print an install hint vs a \"check your BEADS_DOLT_BIN setting\" hint)\n// without parsing message text.\nvar (\n\t// ErrNotFound means no candidate dolt binary could be located at all:\n\t// an explicit env/sidecar path did not exist, or exec.LookPath found\n\t// nothing on PATH.\n\tErrNotFound = errors.New(\"dolt binary not found\")\n\n\t// ErrNotExecutable means a candidate path exists but is not usable as\n\t// an executable: it is a directory, or it is a regular file lacking\n\t// the executable bit. This is distinct from ErrNotFound because the\n\t// remediation is different — the path is real, but the file itself is\n\t// wrong (wrong permissions, wrong kind of file), which is more likely\n\t// a misconfiguration than a missing install.\n\tErrNotExecutable = errors.New(\"dolt path is not executable\")\n\n\t// ErrProbeFailed covers everything that can go wrong actually running\n\t// `<path> version`: the exec call itself failing (including exec\n\t// format errors from architecture/loader mismatches), the process\n\t// timing out, or the process exiting non-zero. These are grouped\n\t// together because callers generally respond to all of them the same\n\t// way (probe failed, do not proceed) even though the underlying causes\n\t// differ; the wrapped error's message still carries the specific cause.\n\tErrProbeFailed = errors.New(\"dolt version probe failed\")\n","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltversion/errors.go#L1-L32","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install Dolt (e.g. `brew install dolt` or download from dolthub) so `dolt` is on PATH","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","Fix PATH in the execution environment (systemd unit, cron, CI) so the dolt install location is included"],"exampleFix":"// before\nexport BEADS_DOLT_BIN=/usr/local/bin/doltt\n// after\nexport BEADS_DOLT_BIN=/usr/local/bin/dolt  # verify with: test -x \"$BEADS_DOLT_BIN\"","handlingStrategy":"type-guard","validationCode":"p := os.Getenv(\"BEADS_DOLT_BIN\")\nif p != \"\" {\n    if _, err := os.Stat(p); err != nil {\n        return fmt.Errorf(\"BEADS_DOLT_BIN does not exist: %s\", p)\n    }\n} else if _, err := exec.LookPath(\"dolt\"); err != nil {\n    return fmt.Errorf(\"dolt not installed or not on PATH\")\n}","typeGuard":"func IsDoltNotFound(err error) bool {\n    return errors.Is(err, doltversion.ErrNotFound)\n}","tryCatchPattern":"if _, err := doltversion.Resolve(); err != nil {\n    if errors.Is(err, doltversion.ErrNotFound) {\n        // print install hint (or \"check BEADS_DOLT_BIN\" if env var was set)\n    }\n    return err\n}","preventionTips":["Install dolt and verify `which dolt` before running bd","Check BEADS_DOLT_BIN with `test -e` in shell profiles/scripts","In CI/systemd, explicitly add the dolt install dir to PATH"],"tags":["go","binary-lookup","path","dolt"],"backgroundTag":"binary-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}