{"record":{"id":"d9f27b213429c7d1","repo":"gastownhall/beads","slug":"errnotfound-d9f27b","errorCode":"ErrNotFound","errorMessage":"%w: dolt not found on PATH: %v","messagePattern":"%w: dolt not found on PATH: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltversion/resolve.go","lineNumber":142,"sourceCode":"\t\t}\n\t\treturn abs, SourceEnv, nil\n\t}\n\n\tif opts.SidecarValue != \"\" {\n\t\tabs, err := filepath.Abs(opts.SidecarValue)\n\t\tif err != nil {\n\t\t\treturn \"\", SourceSidecar, fmt.Errorf(\"sidecar dolt binary %q: resolving absolute path: %w\", opts.SidecarValue, err)\n\t\t}\n\t\tabs = completeExecutableExt(abs)\n\t\tif err := validateExplicitPath(abs); err != nil {\n\t\t\treturn \"\", SourceSidecar, fmt.Errorf(\"sidecar dolt binary %q: %w\", opts.SidecarValue, err)\n\t\t}\n\t\treturn abs, SourceSidecar, nil\n\t}\n\n\tpath, err := exec.LookPath(\"dolt\")\n\tif err != nil {\n\t\treturn \"\", SourcePath, fmt.Errorf(\"%w: dolt not found on PATH: %v\", ErrNotFound, err)\n\t}\n\treturn path, SourcePath, nil\n}\n\n// completeExecutableExt completes a Windows executable extension on an\n// explicitly-named path spelled without one: BEADS_DOLT_BIN=C:\\tools\\dolt\n// should find C:\\tools\\dolt.exe the same way cmd.exe or exec.LookPath\n// would. os.Lstat has no PATHEXT concept, so without this the explicit\n// path reported \"not found\" while dolt.exe sat right there. The exact\n// spelled path wins when it exists (an operator who names an extensionless\n// file gets that file); only when it does not is exec.LookPath consulted —\n// on Windows, LookPath applies PATHEXT completion to paths that contain a\n// separator without searching PATH. Non-Windows returns path unchanged:\n// there, Unix has no implied-extension convention and LookPath's extra\n// checks would only duplicate validateExplicitPath with a different error\n// taxonomy.\nfunc completeExecutableExt(path string) string {\n\tif runtime.GOOS != \"windows\" {","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltversion/resolve.go#L124-L160","documentation":"Resolve wraps ErrNotFound when no explicit override (env or sidecar) is set and exec.LookPath(\"dolt\") cannot find a dolt executable anywhere on the process's PATH. This is the final precedence level: PATH resolution failed and there is nothing to fall back to, so managed proxied-server mode cannot start.","triggerScenarios":"Calling Resolve with empty EnvValue and SidecarValue while no executable named \"dolt\" exists in any directory listed in the PATH environment variable.","commonSituations":"Dolt simply not installed; dolt installed but not on PATH in service/CI/container contexts (systemd units, cron, Docker images) that have a minimal PATH; installed via package manager under a name the service user can't see.","solutions":["Install dolt (e.g. brew install dolt or download from dolt releases)","Add dolt's directory to PATH for the process environment (check PATH inside the actual service context, not your shell)","Set BEADS_DOLT_BIN to the absolute path of a known dolt binary as an explicit override","In containers, copy the dolt binary into the image and reference it via BEADS_DOLT_BIN"],"exampleFix":"// before\n# systemd unit: Environment=PATH=/usr/bin:/bin   (dolt is in /usr/local/bin)\n// after\nEnvironment=PATH=/usr/local/bin:/usr/bin:/bin\n# or\nEnvironment=BEADS_DOLT_BIN=/usr/local/bin/dolt","handlingStrategy":"fallback","validationCode":"if _, err := exec.LookPath(\"dolt\"); err != nil {\n    return fmt.Errorf(\"dolt not found on PATH; install it or set BEADS_DOLT_BIN\")\n}","typeGuard":null,"tryCatchPattern":"path, src, err := doltversion.Resolve(opts)\nif errors.Is(err, doltversion.ErrNotFound) {\n    return fmt.Errorf(\"dolt is not installed or not on PATH: %w\", err)\n}","preventionTips":["Ensure dolt is installed in service/CI/container images","Set PATH explicitly in systemd/cron/container environments","Pin BEADS_DOLT_BIN to an absolute path for reproducible deployments","Bake the dolt binary into Docker images rather than relying on host PATH"],"tags":["go","dolt","binary-resolution","path","env-var"],"backgroundTag":"executable-not-on-path","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}