gastownhall/beads · error

dolt path is not executable

Error message

dolt path is not executable

What it means

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.

Source

Thrown at internal/doltversion/errors.go:22

// 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")

	// ErrUnparseableVersion means the probe ran and produced output, but
	// ParseVersion could not extract a dotted version number from it —
	// most commonly the signature of a dev/custom build whose `dolt
	// version` output doesn't follow the usual pattern, not of a broken or
	// missing binary. Probe itself still returns this as a hard error (the
	// caller asked for a parsed version and didn't get one), but
	// ProbeWithPolicy demotes it to a *Warning rather than propagating it
	// as an error — see ProbeWithPolicy's doc comment for why.

View on GitHub (pinned to 71377f2769)

Solutions

1. chmod +x the file at the configured path (e.g. `chmod +x "$BEADS_DOLT_BIN"`)
2. Point BEADS_DOLT_BIN at the dolt binary file itself, not its containing directory
3. If the path is otherwise unusable, unset BEADS_DOLT_BIN and let Resolve fall back to a working PATH lookup

Example fix

// before
export BEADS_DOLT_BIN=/opt/dolt          # directory
// after
export BEADS_DOLT_BIN=/opt/dolt/dolt && chmod +x /opt/dolt/dolt

p := os.Getenv("BEADS_DOLT_BIN")
if p != "" {
    fi, err := os.Stat(p)
    if err != nil || fi.IsDir() || fi.Mode()&0o111 == 0 {
        return fmt.Errorf("BEADS_DOLT_BIN %s is a directory or lacks the execute bit", p)
    }
}

func IsDoltNotExecutable(err error) bool {
    return errors.Is(err, doltversion.ErrNotExecutable)
}

if _, err := doltversion.Resolve(); err != nil {
    if errors.Is(err, doltversion.ErrNotExecutable) {
        // hint: chmod +x the path or point BEADS_DOLT_BIN at the binary file
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to remove Dolt database: %w
• failed to create backup directory: %w
• failed to create temp file: %w
• failed to create backup file: %w
• %d artifact(s) could not be removed

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