{"record":{"id":"e26dbf5c4646a0a8","repo":"gastownhall/beads","slug":"failed-to-start-dolt-server-after-d-attempts-w","errorCode":null,"errorMessage":"failed to start dolt server after %d attempts: %w\nCorrupt manifest with no recoverable data detected (GH#3290) in:\n  %s\nRun 'bd doctor --fix' to back up the corrupt database(s) and reinitialize.\nCheck logs: %s","messagePattern":"failed to start dolt server after (.+?) attempts: %w\nCorrupt manifest with no recoverable data detected \\(GH#3290\\) in:\n  (.+?)\nRun 'bd doctor --fix' to back up the corrupt database\\(s\\) and reinitialize\\.\nCheck logs: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/doltserver/doltserver.go","lineNumber":1470,"sourceCode":"\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\"+\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 {","sourceCodeStart":1452,"sourceCodeEnd":1488,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L1452-L1488","documentation":"After all start attempts fail, Start() checks detectCorruptManifest(beadsDir, doltDir). If an unclean shutdown left a corrupt .dolt manifest with no recoverable data (GH#3290 / bd-6dnrw.6), the error is augmented with the affected directories and an instruction to run 'bd doctor --fix'. Repair is deliberately not automatic because reinitializing .dolt is destructive.","triggerScenarios":"All spawn attempts exhausted (lastErr set, commonly bind failures or immediate exits) AND detectCorruptManifest finds corrupt manifest directories.","commonSituations":"Machine lost power or the process was SIGKILLed mid-write, leaving a truncated/invalid manifest; Dolt data dir restored from a partial backup.","solutions":["Run bd doctor --fix to back up the corrupt database(s) and reinitialize the affected .dolt directories.","Restore the data dir from a good backup/git remote (bd dolt pull) instead of reinitializing if data must be preserved.","Fix the root cause of unclean shutdowns (avoid SIGKILL, ensure clean OS shutdown, check disk health).","Re-sync from the git remote after repair: bd dolt pull."],"exampleFix":"// before\nbd start\n// failed to start ... Corrupt manifest (GH#3290) in: ~/.beads/.dolt/...\n// after\nbd doctor --fix\nbd dolt pull\nbd start","handlingStrategy":"try-catch","validationCode":"// pre-check manifest health before starting\nconst manifest = path.join(dataDir, '.dolt', 'noms', 'manifest.json');\ntry { JSON.parse(await fs.readFile(manifest, 'utf8')); }\ncatch { console.error('manifest unreadable — run bd doctor --fix'); }","typeGuard":"null","tryCatchPattern":"try {\n  await bdStart();\n} catch (e) {\n  if (/Corrupt manifest/.test(e.message)) {\n    await run('bd', ['doctor', '--fix']);  // backs up + reinitializes\n    await run('bd', ['dolt', 'pull']);     // restore from remote\n    return bdStart();\n  }\n  throw e;\n}","preventionTips":["Shut down bd cleanly; avoid SIGKILL on the server.","Sync regularly so the git remote has current data (bd dolt push).","Ensure clean OS shutdowns and healthy disks (SMART checks).","Back up the data dir before risky operations."],"tags":["corruption","manifest","recovery","startup"],"backgroundTag":"corrupt-dolt-manifest","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}