gastownhall/beads · error

dolt version probe failed

Error message

dolt version probe failed

What it means

ErrProbeFailed is the doltversion sentinel for any failure while actually running `<path> version`: exec failing to start (including exec format errors from architecture/loader mismatch), the process timing out, or exiting non-zero. The causes are grouped because callers respond identically (probe failed, do not proceed); the wrapped error via %w carries the specific underlying cause.

Source

Thrown at internal/doltversion/errors.go:31

	// 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.
	ErrUnparseableVersion = errors.New("dolt version output is unparseable")
)

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause in the error and fix accordingly — for exec format errors, download the dolt build matching your OS/architecture
2. Reinstall/replace the binary (fresh download, verify checksum) if it is corrupt
3. Run `<path> version` manually to see the actual failure and reproduce it outside bd
4. If the probe times out on a slow machine, check system load / disk and ensure the binary isn't on a stalled network mount

Example fix

// before
export BEADS_DOLT_BIN=~/Downloads/dolt-linux-arm64   # on amd64 host
// after
curl -L https://github.com/dolthub/dolt/releases/latest/download/dolt-linux-amd64.tar.gz | tar xz
export BEADS_DOLT_BIN=$PWD/dolt-linux-amd64/dolt

func IsDoltProbeFailed(err error) bool {
    return errors.Is(err, doltversion.ErrProbeFailed)
}

if _, err := doltversion.Probe(ctx, path); err != nil {
    if errors.Is(err, doltversion.ErrProbeFailed) {
        // inspect wrapped cause: exec format error -> wrong arch build;
        // timeout -> slow host; exit != 0 -> run `<path> version` manually
    }
    return err
}

When it happens

Trigger: Calling doltversion.Probe with a binary that cannot be executed (wrong architecture, corrupt download), one that hangs past the probe timeout, or one whose `dolt version` exits non-zero.

Common situations: Downloading a dolt binary built for the wrong OS/arch (e.g. arm64 binary on amd64, or a Linux binary on macOS); a truncated/corrupt download; a broken wrapper script returning non-zero; resource-constrained environments causing the probe to time out.

Related errors

• dolt directory is required
• dolt binary not found
• dolt path is not executable
• dolt version output is unparseable
• dolt sql-server exited before listener became ready

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