{"record":{"id":"71547be4821ab3fd","repo":"gastownhall/beads","slug":"server-started-pid-d-but-not-accepting-connecti","errorCode":null,"errorMessage":"server started (PID %d) but not accepting connections on port %d: %w\n\n%s","messagePattern":"server started \\(PID (.+?)\\) but not accepting connections on port (.+?): %w\n\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":1503,"sourceCode":"\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}\n\n\t// Wait for server to accept connections\n\tif err := waitForReady(cfg.Host, actualPort, readyTimeout()); 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\t_ = os.Remove(portPath(beadsDir))\n\t\tif hasJournalCorruption, logErr := logHasCorruptJournalError(logPath(beadsDir)); logErr == nil && hasJournalCorruption {\n\t\t\treturn nil, fmt.Errorf(\"server started (PID %d) but not accepting connections on port %d: %w\\n\\n%s\",\n\t\t\t\tpid, actualPort, err, corruptJournalRecoveryHint(beadsDir))\n\t\t}\n\t\treturn nil, fmt.Errorf(\"server started (PID %d) but not accepting connections on port %d: %w\\nCheck logs: %s\",\n\t\t\tpid, actualPort, err, logPath(beadsDir))\n\t}\n\n\treturn &State{\n\t\tRunning: true,\n\t\tPID:     pid,\n\t\tPort:    actualPort,\n\t\tDataDir: doltDir,\n\t}, nil\n}\n\n// EnsureGlobalDatabase connects to the shared Dolt server and creates the\n// beads_global database if it doesn't already exist. This is idempotent and\n// safe to call on every shared server init. Schema initialization and config\n// seeding (issue prefix, project ID) are handled by the store layer when the","sourceCodeStart":1485,"sourceCodeEnd":1521,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L1485-L1521","documentation":"This error is returned by doltserver.Start when the dolt sql-server process spawned successfully (its PID is alive) but waitForReady never observed a MySQL handshake on the bound port within the ready timeout. Before returning, Start kills the process and removes the PID/port files; if the server log contains journal-corruption errors, the generic message is upgraded to include corruptJournalRecoveryHint with recovery steps.","triggerScenarios":"waitForReady(cfg.Host, actualPort, readyTimeout()) exhausts its deadline — the server process is running but the MySQL engine never starts accepting/greeting connections, e.g. Dolt is stuck initializing a corrupt journal, the log shows corrupt-journal errors, or the server hangs during startup (slow disk, resource starvation).","commonSituations":"Unclean shutdown (power loss, SIGKILL) leaving a corrupt Dolt journal; a shared multi-tenant server starved of CPU/disk; container resource limits preventing Dolt from finishing startup; very large databases taking longer than the ready timeout to open; server crashing after the initial liveness check but before listening.","solutions":["Read the server log at the path printed in the error (bd dolt logs / .beads/dolt-server.log) for the underlying startup error","If the message includes the journal-corruption hint, follow it: back up and reinitialize via 'bd doctor --fix' (repair is deliberately not automatic)","Check for a hung dolt process (ps aux | grep dolt sql-server) and kill it before retrying","Increase the readiness timeout (BEADS_DOLT_READY_TIMEOUT) if the database is large but healthy","Verify the container/host has enough memory, CPU, and disk I/O for Dolt startup"],"exampleFix":"// before\n// error: server started (PID 12345) but not accepting connections on port 41017: timeout...\n//   [journal corruption hint follows]\n// after\n// $ bd doctor --fix   # backs up corrupt db and reinitializes .dolt\n// $ bd dolt start","handlingStrategy":"try-catch","validationCode":"// Before Start, check for known corruption markers so you can repair proactively\nif dirs, detErr := doltserver.DetectCorruptManifestIfAvailable(beadsDir); detErr == nil && len(dirs) > 0 {\n    // run: bd doctor --fix  before attempting startup\n    fmt.Fprintf(os.Stderr, \"corrupt manifest detected in %v; run bd doctor --fix\\n\", dirs)\n}","typeGuard":null,"tryCatchPattern":"state, err := doltserver.Start(cfg)\nif err != nil {\n    var logHint string\n    if strings.Contains(err.Error(), \"journal\") || strings.Contains(err.Error(), \"corrupt\") {\n        // corruption path: run bd doctor --fix, do not blind-retry\n        fmt.Fprintln(os.Stderr, \"corruption suspected; run: bd doctor --fix\")\n        os.Exit(1)\n    }\n    _ = logHint\n    return fmt.Errorf(\"dolt server start failed: %w (check %s)\", err, doltserver.LogPath(beadsDir))\n}","preventionTips":["Always stop the server with bd dolt stop (graceful) instead of SIGKILL","Enable graceful host shutdowns so the dolt process is never hard-killed","Read .beads/dolt-server.log immediately when startup is slow","Raise BEADS_DOLT_READY_TIMEOUT for large databases","Run bd doctor periodically to catch journal/manifest issues early"],"tags":["go","server-startup","timeout","dolt","journal-corruption"],"backgroundTag":"server-not-accepting-connections","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}