{"record":{"id":"e86e72f4864c089c","repo":"gastownhall/beads","slug":"server-started-pid-d-but-not-accepting-connecti-e86e72","errorCode":null,"errorMessage":"server started (PID %d) but not accepting connections on port %d: %w\nCheck logs: %s","messagePattern":"server started \\(PID (.+?)\\) but not accepting connections on port (.+?): %w\nCheck logs: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":1506,"sourceCode":"\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\n// global database is first opened with CreateIfMissing=true.\n//\n// Returns nil if the database already exists or was successfully created.","sourceCodeStart":1488,"sourceCodeEnd":1524,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L1488-L1524","documentation":"This is the non-corruption variant of the same Start readiness failure: the dolt sql-server process spawned (PID alive) but never accepted connections on its port within readyTimeout(), and the log scan found no corrupt-journal errors. Start kills the process, removes the PID and port state files, and returns this error pointing the operator at the server log for the real cause.","triggerScenarios":"waitForReady times out with a healthy-looking journal: the server binds late or never — e.g. dolt binary crash after the 200ms liveness check (use `dolt sql-server` failing on config), port firewall/loopback issues, wrong host binding (cfg.Host mismatch), or startup slower than the ready timeout.","commonSituations":"dolt version incompatible with the data directory causing a crash mid-init; server bound to a different interface than cfg.Host; SELinux/firewall blocking loopback; resource-limited containers; first-start on a huge dataset exceeding the readiness window; broken dolt install missing required shared libraries.","solutions":["Inspect the log file named in the error (.beads/dolt-server.log or bd dolt logs) for the actual startup failure","Run the dolt binary manually (`dolt sql-server --config ...`) in the data dir to see the crash/error directly","Check dolt is on a compatible, working version (`dolt version`; upgrade or reinstall)","Confirm cfg.Host is reachable (default 127.0.0.1) and no firewall blocks the port; retry with an explicit free port","Raise the ready timeout if startup is merely slow (large DB, slow disk) and retry"],"exampleFix":"// before\n// error: server started (PID 12345) but not accepting connections on port 41017: timeout after 15s waiting for server at 127.0.0.1:41017\n//   Check logs: /repo/.beads/dolt-server.log\n// after: diagnose via the log, then e.g.\n// $ tail -50 /repo/.beads/dolt-server.log   # shows real cause (crash, bind error)\n// $ dolt version && dolt config list       # verify healthy dolt install\n// $ bd dolt start                          # retry","handlingStrategy":"try-catch","validationCode":"// Pre-flight: verify the dolt binary works and the host is bindable\nif out, err := exec.Command(\"dolt\", \"version\").Output(); err != nil {\n    return fmt.Errorf(\"dolt binary broken: %w\", err)\n}\nln, lerr := net.Listen(\"tcp\", net.JoinHostPort(cfg.Host, \"0\"))\nif lerr != nil {\n    return fmt.Errorf(\"host %s not bindable: %w\", cfg.Host, lerr)\n}\nln.Close()","typeGuard":null,"tryCatchPattern":"state, err := doltserver.Start(cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"not accepting connections\") {\n        log := doltserver.LogPath(beadsDir)\n        if data, rerr := os.ReadFile(log); rerr == nil {\n            return fmt.Errorf(\"start failed; server log tail: %s\", tail(string(data), 40))\n        }\n    }\n    return err\n}","preventionTips":["Keep the dolt binary up to date and compatible with the data directory","Pin cfg.Host to a valid local interface (127.0.0.1) unless remote access is required","Ensure SELinux/firewall permits loopback connections","Use bd dolt restart instead of concurrent stop/start from multiple processes","Increase the ready timeout on slow storage or very large databases"],"tags":["go","server-startup","timeout","dolt","port-bind"],"backgroundTag":"server-not-accepting-connections","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}