{"record":{"id":"520b87dce33b00f4","repo":"gastownhall/beads","slug":"dolt-server-is-not-running-on-port-d-and-auto-st","errorCode":null,"errorMessage":"Dolt server is not running on port %d, and auto-start is suppressed because the server is externally managed (dolt.auto-start: false or explicit port configured).\n\nStart the external server, or enable auto-start to allow bd to manage the server.\n  To start manually: bd dolt start\n  To check status: bd dolt status","messagePattern":"Dolt server is not running on port (.+?), and auto-start is suppressed because the server is externally managed \\(dolt\\.auto-start: false or explicit port configured\\)\\.\n\nStart the external server, or enable auto-start to allow bd to manage the server\\.\n  To start manually: bd dolt start\n  To check status: bd dolt status","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":982,"sourceCode":"\t}\n\n\t// If the server mode is External (explicit port in metadata.json,\n\t// shared server mode, etc.), do not start a per-project server —\n\t// it would conflict with the external one.\n\tmode := ResolveServerMode(beadsDir)\n\tif mode == ServerModeExternal {\n\t\tcfg := DefaultConfig(beadsDir)\n\t\tif host, ok := externalNonLocalhostHost(beadsDir); ok {\n\t\t\t// Configured for a non-localhost external server:\n\t\t\t// \"bd dolt start\" is not the right advice (GH#3518).\n\t\t\treturn 0, false, fmt.Errorf(\"Dolt server at %s:%d is unreachable, and bd will not \"+\n\t\t\t\t\"start a local server because an external one is configured.\\n\\n\"+\n\t\t\t\t\"Verify the external server is running and reachable from this host:\\n\"+\n\t\t\t\t\"  nc -zv %s %d  # or curl %s:%d for an HTTP-style check\\n\"+\n\t\t\t\t\"  bd dolt status   # detailed external-server check\",\n\t\t\t\thost, cfg.Port, host, cfg.Port, host, cfg.Port)\n\t\t}\n\t\treturn 0, false, fmt.Errorf(\"Dolt server is not running on port %d, and auto-start is suppressed \"+\n\t\t\t\"because the server is externally managed (dolt.auto-start: false or explicit port configured).\\n\\n\"+\n\t\t\t\"Start the external server, or enable auto-start to allow bd to manage the server.\\n\"+\n\t\t\t\"  To start manually: bd dolt start\\n\"+\n\t\t\t\"  To check status: bd dolt status\", cfg.Port)\n\t}\n\n\t// Defense-in-depth: if dolt.auto-start is explicitly disabled in\n\t// config.yaml or env, never spawn a server even if the caller\n\t// somehow reached this point (e.g. stale AutoStart=true in config).\n\tif IsAutoStartDisabled() {\n\t\tcfg := DefaultConfig(beadsDir)\n\t\tif host, ok := externalNonLocalhostHost(beadsDir); ok {\n\t\t\treturn 0, false, fmt.Errorf(\"Configured Dolt server at %s:%d is unreachable, and auto-start \"+\n\t\t\t\t\"is disabled (dolt.auto-start: false in config.yaml or BEADS_DOLT_AUTO_START=0).\\n\\n\"+\n\t\t\t\t\"This is an external server; bd will not start it. Verify it is running:\\n\"+\n\t\t\t\t\"  nc -zv %s %d  # or curl %s:%d for an HTTP-style check\\n\"+\n\t\t\t\t\"  bd dolt status   # detailed external-server check\",\n\t\t\t\thost, cfg.Port, host, cfg.Port, host, cfg.Port)","sourceCodeStart":964,"sourceCodeEnd":1000,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L964-L1000","documentation":"In External server mode on a localhost-style configuration, EnsureRunningDetailed suppresses auto-start because the server is externally managed (dolt.auto-start disabled or an explicit port configured). If the server is not running, this error tells the operator to start it manually or re-enable auto-start, instead of bd silently spawning a competing local server.","triggerScenarios":"EnsureRunning/EnsureRunningDetailed(beadsDir) where ResolveServerMode==ServerModeExternal with a localhost host (or no non-localhost host), the PID file says not-running, and auto-start is suppressed due to dolt.auto-start: false or an explicitly configured port.","commonSituations":"User set an explicit port in config.yaml expecting bd to still manage the server, or disabled auto-start earlier and forgot; then ran bd after a reboot without running bd dolt start.","solutions":["Start the external server manually: bd dolt start","Re-enable auto-start (remove dolt.auto-start: false from config.yaml or unset BEADS_DOLT_AUTO_START=0) so bd manages the server again","Check current state with bd dolt status","If the explicit port was set unintentionally, clear it so bd falls back to managed auto-start"],"exampleFix":"// before: config.yaml\nauto-start: false\n// after: let bd manage the server\nauto-start: true\n# or run manually: bd dolt start","handlingStrategy":"fallback","validationCode":"// Check server is up or auto-start allowed before calling\nport, _ := doltserver.EnsureRunning(beadsDir) // probe via IsRunning instead:\nstate, err := doltserver.IsRunning(serverDir)\nif err != nil || !state.Running {\n    // either run `bd dolt start` first or ensure auto-start is enabled in config\n}","typeGuard":"func isAutoStartSuppressed(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"auto-start is suppressed\")\n}","tryCatchPattern":"port, err := doltserver.EnsureRunning(beadsDir)\nif err != nil && isAutoStartSuppressed(err) {\n    if out, runErr := exec.Command(\"bd\", \"dolt\", \"start\").CombinedOutput(); runErr != nil {\n        return fmt.Errorf(\"manual start failed: %v: %s\", runErr, out)\n    }\n    port, err = doltserver.EnsureRunning(beadsDir)\n}","preventionTips":["Run bd dolt start after reboots when auto-start is disabled","Don't set explicit ports unless you also manage server lifecycle","Keep dolt.auto-start: true for single-user local workflows","Document the external-management contract for your team's machines"],"tags":["external-server","auto-start","configuration","dolt"],"backgroundTag":"server-not-running","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}