{"record":{"id":"0bb10ea38c66a893","repo":"gastownhall/beads","slug":"failed-to-start-dolt-server-after-d-attempts-w-0bb10e","errorCode":null,"errorMessage":"failed to start dolt server after %d attempts: %w\nCheck logs: %s","messagePattern":"failed to start dolt server after (.+?) attempts: %w\nCheck logs: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":1475,"sourceCode":"\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\"+\n\t\t\t\t\t\"Corrupt manifest with no recoverable data detected (GH#3290) in:\\n  %s\\n\"+\n\t\t\t\t\t\"Run 'bd doctor --fix' to back up the corrupt database(s) and reinitialize.\\nCheck logs: %s\",\n\t\t\t\t\tattempts, lastErr, strings.Join(dirs, \"\\n  \"), logPath(beadsDir))\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"failed to start dolt server after %d attempts: %w\\nCheck logs: %s\",\n\t\t\t\tattempts, lastErr, logPath(beadsDir))\n\t\t}\n\t}\n\n\t// Write PID and port files\n\tif err := os.WriteFile(pidPath(beadsDir), []byte(strconv.Itoa(pid)), 0600); err != nil {\n\t\tif proc, findErr := os.FindProcess(pid); findErr == nil {\n\t\t\t_ = proc.Kill()\n\t\t}\n\t\treturn nil, fmt.Errorf(\"writing PID file: %w\", err)\n\t}\n\tif err := writePortFile(beadsDir, actualPort); err != nil {\n\t\tif proc, findErr := os.FindProcess(pid); findErr == nil {\n\t\t\t_ = proc.Kill()\n\t\t}\n\t\t_ = os.Remove(pidPath(beadsDir))\n\t\treturn nil, fmt.Errorf(\"writing port file: %w\", err)\n\t}","sourceCodeStart":1457,"sourceCodeEnd":1493,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L1457-L1493","documentation":"The generic failure path when all dolt sql-server start attempts are exhausted and no corrupt manifest was detected. It wraps the last attempt's error (lastErr) and points at the server log file. This is what users see when the specific GH#3290 corruption branch does not apply.","triggerScenarios":"Every attempt failed (bind conflicts, immediate exits, config issues) and detectCorruptManifest found nothing — e.g. port held by a foreign process across all retries.","commonSituations":"Persistent port conflict; repeated spawn failures due to a broken dolt binary or PATH; resource limits (fork failures); misconfigured host binding (e.g. bad interface address).","solutions":["Read the referenced log file (last line of the error) for the child's real failure.","Resolve the underlying issue from lastErr: free the port, fix config, or verify the dolt binary runs (dolt version).","Try an ephemeral port (port 0) to rule out port conflicts.","Check system resources: ulimits, memory, and that the host address is valid on this machine."],"exampleFix":"// before: bind to a nonexistent host IP\nBD_HOST=10.0.0.99 bd start  # attempts exhausted\n// after\nBD_HOST=127.0.0.1 bd start   # or unset to use default","handlingStrategy":"try-catch","validationCode":"// sanity checks before starting\nawait fs.access(path.join(dataDir, '.dolt'), fs.constants.W_OK);\nawait execFile('dolt', ['version']); // dolt binary works\nconst hostIfaces = Object.keys(os.networkInterfaces());\nif (cfgHost && !hostIfaces.includes(cfgHost) && cfgHost !== 'localhost' && cfgHost !== '127.0.0.1')\n  console.warn('configured host not present on this machine');","typeGuard":"null","tryCatchPattern":"try {\n  await bdStart();\n} catch (e) {\n  const m = /failed to start dolt server after (\\d+) attempts/.exec(e.message);\n  if (m && !/Corrupt manifest/.test(e.message)) {\n    const logTail = await readTail(logFile); // log path is in the error\n    // act on logTail: port conflict, bad config, resource limits\n  }\n  throw e;\n}","preventionTips":["Always read the referenced log file first — it names the real cause.","Validate configured host/port values before start.","Keep the dolt binary on PATH and up to date.","Check ulimits and memory on constrained hosts."],"tags":["startup","process","retry-exhausted"],"backgroundTag":"server-start-exhausted-retries","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}