{"record":{"id":"b4ed52e4b03c44bd","repo":"gastownhall/beads","slug":"dolt-sql-server-exited-immediately-on-port-d-att","errorCode":null,"errorMessage":"dolt sql-server exited immediately on port %d (attempt %d/%d)","messagePattern":"dolt sql-server exited immediately on port (.+?) \\(attempt (.+?)/(.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":1452,"sourceCode":"\t\t\t// restarted. os/exec does not close those; mark them first.\n\t\t\tsanitizeInheritedFDs()\n\n\t\t\tif startErr := cmd.Start(); startErr != nil {\n\t\t\t\tlastErr = startErr\n\t\t\t\tif !explicitPort {\n\t\t\t\t\tcontinue // retry with a new ephemeral port\n\t\t\t\t}\n\t\t\t\tbreak\n\t\t\t}\n\n\t\t\tpid = cmd.Process.Pid\n\t\t\t_ = cmd.Process.Release()\n\n\t\t\t// Quick check: did the process exit immediately (bind failure)?\n\t\t\t// Give it a moment to fail on port bind before proceeding.\n\t\t\ttime.Sleep(200 * time.Millisecond)\n\t\t\tif !isProcessAlive(pid) {\n\t\t\t\tlastErr = fmt.Errorf(\"dolt sql-server exited immediately on port %d (attempt %d/%d)\", actualPort, i+1, attempts)\n\t\t\t\tpid = 0\n\t\t\t\tif !explicitPort {\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t\tbreak\n\t\t\t}\n\n\t\t\tlastErr = nil\n\t\t\tbreak\n\t\t}\n\t\t_ = logFile.Close()\n\n\t\tif lastErr != nil {\n\t\t\t// GH#3290 / bd-6dnrw.6: unclean-shutdown manifest corruption is\n\t\t\t// detected here but never auto-repaired — reinitializing .dolt is\n\t\t\t// destructive, so repair stays behind explicit bd doctor --fix.\n\t\t\tif dirs, detErr := detectCorruptManifest(beadsDir, doltDir); detErr == nil && len(dirs) > 0 {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to start dolt server after %d attempts: %w\\n\"+","sourceCodeStart":1434,"sourceCodeEnd":1470,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L1434-L1470","documentation":"Start() sleeps 200ms after spawning dolt sql-server and checks isProcessAlive(pid). A process that dies within that window almost always failed to bind its port (bind failure), so Start records 'dolt sql-server exited immediately on port %d (attempt %d/%d)' as lastErr and retries or breaks depending on whether the port was explicit.","triggerScenarios":"Child dolt sql-server exits before the 200ms aliveness check — usually 'address already in use' bind failure, but also invalid config or data-dir corruption causing instant exit.","commonSituations":"Another process bound the explicit port between allocation and bind (TOCTOU); orphaned dolt sql-server still holding the port; malformed managed config YAML; corrupt .dolt manifest crashing the server at boot.","solutions":["Inspect the server log (path printed by the final wrapped error) for the child's actual exit reason.","Free the port: find the holder with ss -ltnp / lsof -i :PORT and stop it, or pick another port.","Run bd doctor --fix if the final error mentions corrupt manifest (GH#3290).","Retry with port 0 (ephemeral) so the OS allocates a fresh port per attempt."],"exampleFix":"// before\nBD_PORT=4141 bd start\n// error: exited immediately on port 4141\n// after: check logs and free the port, or\nBD_PORT=0 bd start","handlingStrategy":"retry","validationCode":"// check the port is bindable and no orphan dolt is running\nconst inUse = await new Promise(res => {\n  const s = require('net').createServer();\n  s.once('error', () => res(true)); s.listen(port, () => { s.close(); res(false); });\n});\nif (inUse) console.warn(`port ${port} already in use`);","typeGuard":"null","tryCatchPattern":"try {\n  await bdStart();\n} catch (e) {\n  if (/exited immediately on port/.test(e.message)) {\n    await checkLogFile();   // find real exit reason\n    await killOrphanedDolt();\n    await retryWithEphemeralPort();\n  }\n  throw e;\n}","preventionTips":["Use ephemeral ports (port 0) to avoid TOCTOU bind races.","Clean up orphaned dolt sql-server processes after crashes.","Keep the managed config valid — don't hand-edit dolt-server.yaml.","Run bd doctor if starts keep failing."],"tags":["process","port","bind","startup"],"backgroundTag":"address-already-in-use","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}