{"record":{"id":"78fe6e11b5605052","repo":"gastownhall/beads","slug":"dolt-path-is-not-executable","errorCode":null,"errorMessage":"dolt path is not executable","messagePattern":"dolt path is not executable","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltversion/errors.go","lineNumber":22,"sourceCode":"\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\n\t// ErrUnparseableVersion means the probe ran and produced output, but\n\t// ParseVersion could not extract a dotted version number from it —\n\t// most commonly the signature of a dev/custom build whose `dolt\n\t// version` output doesn't follow the usual pattern, not of a broken or\n\t// missing binary. Probe itself still returns this as a hard error (the\n\t// caller asked for a parsed version and didn't get one), but\n\t// ProbeWithPolicy demotes it to a *Warning rather than propagating it\n\t// as an error — see ProbeWithPolicy's doc comment for why.","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltversion/errors.go#L4-L40","documentation":"ErrNotExecutable is a doltversion sentinel meaning a candidate dolt path exists but is not usable as an executable: it is a directory, or it is a regular file without the execute bit. It is deliberately distinct from ErrNotFound because the path is real but the file is wrong — remediation is fixing the file/permissions, not installing Dolt.","triggerScenarios":"BEADS_DOLT_BIN or a resolved sidecar path points to a directory (e.g. the Dolt install folder rather than the binary), or to a non-executable regular file (execute bit stripped, e.g. after copying the binary with cp without -p, or a downloaded release artifact not chmod +x'd); detected by validateExplicitPath during Resolve/Probe.","commonSituations":"Downloading a Dolt release tarball and forgetting `chmod +x dolt`; pointing BEADS_DOLT_BIN at /usr/local/dolt/ instead of the binary inside it; permission-restrictive filesystems or umask stripping the exec bit during extraction.","solutions":["chmod +x the file at the configured path (e.g. `chmod +x \"$BEADS_DOLT_BIN\"`)","Point BEADS_DOLT_BIN at the dolt binary file itself, not its containing directory","If the path is otherwise unusable, unset BEADS_DOLT_BIN and let Resolve fall back to a working PATH lookup"],"exampleFix":"// before\nexport BEADS_DOLT_BIN=/opt/dolt          # directory\n// after\nexport BEADS_DOLT_BIN=/opt/dolt/dolt && chmod +x /opt/dolt/dolt","handlingStrategy":"validation","validationCode":"p := os.Getenv(\"BEADS_DOLT_BIN\")\nif p != \"\" {\n    fi, err := os.Stat(p)\n    if err != nil || fi.IsDir() || fi.Mode()&0o111 == 0 {\n        return fmt.Errorf(\"BEADS_DOLT_BIN %s is a directory or lacks the execute bit\", p)\n    }\n}","typeGuard":"func IsDoltNotExecutable(err error) bool {\n    return errors.Is(err, doltversion.ErrNotExecutable)\n}","tryCatchPattern":"if _, err := doltversion.Resolve(); err != nil {\n    if errors.Is(err, doltversion.ErrNotExecutable) {\n        // hint: chmod +x the path or point BEADS_DOLT_BIN at the binary file\n    }\n    return err\n}","preventionTips":["Always chmod +x downloaded dolt binaries before use","Point BEADS_DOLT_BIN at a file, never a directory","Preserve permissions when copying/archiving binaries (cp -p, tar -p)"],"tags":["go","permissions","filesystem","dolt"],"backgroundTag":"binary-not-executable","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}