{"record":{"id":"b064afeec910a73c","repo":"gastownhall/beads","slug":"dolt-version-probe-failed","errorCode":null,"errorMessage":"dolt version probe failed","messagePattern":"dolt version probe failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltversion/errors.go","lineNumber":31,"sourceCode":"\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.\n\tErrUnparseableVersion = errors.New(\"dolt version output is unparseable\")\n)\n","sourceCodeStart":13,"sourceCodeEnd":43,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltversion/errors.go#L13-L43","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause in the error and fix accordingly — for exec format errors, download the dolt build matching your OS/architecture","Reinstall/replace the binary (fresh download, verify checksum) if it is corrupt","Run `<path> version` manually to see the actual failure and reproduce it outside bd","If the probe times out on a slow machine, check system load / disk and ensure the binary isn't on a stalled network mount"],"exampleFix":"// before\nexport BEADS_DOLT_BIN=~/Downloads/dolt-linux-arm64   # on amd64 host\n// after\ncurl -L https://github.com/dolthub/dolt/releases/latest/download/dolt-linux-amd64.tar.gz | tar xz\nexport BEADS_DOLT_BIN=$PWD/dolt-linux-amd64/dolt","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func IsDoltProbeFailed(err error) bool {\n    return errors.Is(err, doltversion.ErrProbeFailed)\n}","tryCatchPattern":"if _, err := doltversion.Probe(ctx, path); err != nil {\n    if errors.Is(err, doltversion.ErrProbeFailed) {\n        // inspect wrapped cause: exec format error -> wrong arch build;\n        // timeout -> slow host; exit != 0 -> run `<path> version` manually\n    }\n    return err\n}","preventionTips":["Download the dolt build matching your OS/architecture and verify its checksum","Smoke-test `<path> version` manually before wiring the path into BEADS_DOLT_BIN","Avoid binaries on network mounts or stalled disks that can blow the probe timeout"],"tags":["go","exec","binary","dolt"],"backgroundTag":"version-probe-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}