{"record":{"id":"bb824c7e2eb7eb21","repo":"gastownhall/beads","slug":"server-doltserver-start-spawn-dolt-w","errorCode":null,"errorMessage":"server: DoltServer.Start: spawn dolt: %w","messagePattern":"server: DoltServer\\.Start: spawn dolt: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/storage/dbproxy/server/doltserver.go","lineNumber":265,"sourceCode":"\ts.cancel = cancel\n\n\tcmd := exec.CommandContext(managedCtx, s.doltBinExec, args...)\n\tcmd.Dir = s.rootDir\n\tcmd.Stdin = nil\n\tif s.logFile != nil {\n\t\tcmd.Stdout = s.logFile\n\t\tcmd.Stderr = s.logFile\n\t}\n\n\t// The proxied server runs CALL DOLT_PUSH/FETCH in-process; see\n\t// doltserver.ServerSpawnEnv for the guards it needs (GH#4272).\n\tcmd.Env = doltserver.ServerSpawnEnv()\n\n\tif err := cmd.Start(); err != nil {\n\t\ts.eg, s.egCtx, s.cancel = nil, nil, nil\n\t\tcancel()\n\t\tlock.Unlock()\n\t\treturn fmt.Errorf(\"server: DoltServer.Start: spawn dolt: %w\", err)\n\t}\n\n\ts.pid = cmd.Process.Pid\n\tbirth, err := procid.Capture(s.pid)\n\tif err != nil {\n\t\t_ = cmd.Process.Kill()\n\t\t_, _ = cmd.Process.Wait()\n\t\ts.eg, s.egCtx, s.cancel, s.pid = nil, nil, nil, 0\n\t\tcancel()\n\t\tlock.Unlock()\n\t\treturn fmt.Errorf(\"server: DoltServer.Start: capture child birth identity: %w\", err)\n\t}\n\trootID, err := identity.RootID(s.rootDir)\n\tif err != nil {\n\t\t_ = cmd.Process.Kill()\n\t\t_, _ = cmd.Process.Wait()\n\t\ts.eg, s.egCtx, s.cancel, s.pid = nil, nil, nil, 0\n\t\tcancel()","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/server/doltserver.go#L247-L283","documentation":"Start() failed to spawn the managed `dolt sql-server --config <path>` child process (exec.Cmd.Start returned an error). The server state is rolled back and the lock released; the dolt binary was never launched.","triggerScenarios":"cmd.Start() fails at doltserver.go:261 — typically because doltBinExec does not exist or is not executable, the working directory (rootDir) is missing, or fork/exec fails due to resource limits.","commonSituations":"Dolt binary not installed or PATH/env resolution points to a removed path; binary lacks +x permission; wrong architecture binary; container without exec permission on the volume; too many processes (ulimit).","solutions":["Verify the dolt binary path is correct and executable: run `<path-to-dolt> version` manually.","Check rootDir exists and is accessible (cd into it).","Check ulimit -u / PID limits and disk space; fix resource constraints.","Ensure the binary matches the OS/architecture (e.g. not an arm64 binary on x86_64)."],"exampleFix":"// before\nsrv, _ := server.NewDoltServer(\"dolt\", dir, cfgPath, \"\", 0, db) // relies on PATH\n// after\nbin, err := exec.LookPath(\"dolt\")\nif err != nil {\n    log.Fatal(\"dolt binary not found: install dolt and ensure it is on PATH\")\n}\nsrv, _ := server.NewDoltServer(bin, dir, cfgPath, \"\", 0, db)","handlingStrategy":"validation","validationCode":"bin, err := exec.LookPath(doltBin)\nif err != nil {\n    return fmt.Errorf(\"dolt binary %q not found: %w\", doltBin, err)\n}\nif info, err := os.Stat(bin); err != nil || info.IsDir() || info.Mode()&0o111 == 0 {\n    return fmt.Errorf(\"dolt binary %q is not executable\", bin)\n}\nif _, err := exec.Command(bin, \"version\").Output(); err != nil {\n    return fmt.Errorf(\"dolt binary %q cannot run: %w\", bin, err)\n}","typeGuard":null,"tryCatchPattern":"if err := srv.Start(ctx); err != nil {\n    if strings.Contains(err.Error(), \"spawn dolt\") {\n        return fmt.Errorf(\"failed to launch dolt (check DOLT binary path/permissions): %w\", err)\n    }\n    return err\n}","preventionTips":["Resolve the dolt binary with exec.LookPath at startup and fail fast with a clear message.","Verify `dolt version` works in your container/CI image before launching servers.","Keep process ulimits generous in containers.","Pin the dolt binary path in configuration rather than relying on PATH."],"tags":["process-spawn","exec","environment"],"backgroundTag":"exec-command-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}