gastownhall/beads · warning

dolt version output is unparseable

Error message

dolt version output is unparseable

What it means

ErrUnparseableVersion means the dolt binary ran and produced output, but ParseVersion could not extract a dotted version number from it — most commonly a dev/custom build whose `dolt version` output doesn't follow the usual `x.y.z` pattern. Probe returns it as a hard error; ProbeWithPolicy demotes it to a *Warning rather than failing, since the binary itself works.

Source

Thrown at internal/doltversion/errors.go:41

	// 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. Switch to an official Dolt release whose `dolt version` prints a standard dotted version (e.g. 1.x.y)
2. If you must keep the custom build, use ProbeWithPolicy so this is treated as a warning instead of a hard error
3. Inspect `"$BEADS_DOLT_BIN" version` output directly and remove any wrapper/shim that pollutes the output

Example fix

// before
export BEADS_DOLT_BIN=~/src/dolt/dolt   # dev build: prints "dolt dev hash"
// after
export BEADS_DOLT_BIN=/usr/local/bin/dolt  # official release: prints "dolt version 1.41.0"
// or, in code: v, warn, err := doltversion.ProbeWithPolicy(ctx) // warning, not error

out, err := exec.Command(binPath, "version").Output()
if err == nil {
    if _, perr := doltversion.ParseVersion(string(out)); perr != nil {
        // custom/dev build — switch to an official release or use ProbeWithPolicy
    }
}

func IsDoltVersionUnparseable(err error) bool {
    return errors.Is(err, doltversion.ErrUnparseableVersion)
}

if v, err := doltversion.Probe(ctx, path); err != nil {
    if errors.Is(err, doltversion.ErrUnparseableVersion) {
        // binary runs but version text is non-standard; use ProbeWithPolicy
        // which demotes this to a *Warning and proceeds
    }
    return err
}

When it happens

Trigger: ParseVersion or parseToken failing on probe output: calling doltversion.Probe against a dev/custom dolt build printing non-standard version text, a wrapper script that prepends banners/warnings before the version line, or a binary printing localized/garbage output.

Common situations: Running a locally built dolt from source that prints a commit hash instead of a version; wrapper scripts or shell profiles emitting extra output; a `dolt` shim that prints a deprecation notice before the real version string.

Related errors

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

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