{"record":{"id":"2f6d94a026d76aa2","repo":"gastownhall/beads","slug":"dolt-server-at-s-d-is-unreachable-and-bd-will-n","errorCode":null,"errorMessage":"Dolt server at %s:%d is unreachable, and bd will not start a local server because an external one is configured.\n\nVerify the external server is running and reachable from this host:\n  nc -zv %s %d  # or curl %s:%d for an HTTP-style check\n  bd dolt status   # detailed external-server check","messagePattern":"Dolt server at (.+?):(.+?) is unreachable, and bd will not start a local server because an external one is configured\\.\n\nVerify the external server is running and reachable from this host:\n  nc -zv (.+?) (.+?)  # or curl (.+?):(.+?) for an HTTP-style check\n  bd dolt status   # detailed external-server check","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":975,"sourceCode":"\tstate, err := IsRunning(serverDir)\n\tif err != nil {\n\t\treturn 0, false, err\n\t}\n\tif state.Running {\n\t\t_ = EnsurePortFile(serverDir, state.Port)\n\t\treturn state.Port, false, nil\n\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)","sourceCodeStart":957,"sourceCodeEnd":993,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L957-L993","documentation":"EnsureRunningDetailed refuses to start a local server when server mode is External and the configured host is a non-localhost address — starting a per-project local server would be wrong when bd is pointed at a remote/managed instance. When that external server does not respond, this error explains that bd will not auto-start and gives reachability checks (GH#3518).","triggerScenarios":"EnsureRunning/EnsureRunningDetailed(beadsDir) with ResolveServerMode==ServerModeExternal and externalNonLocalhostHost returns a host, but the TCP probe to host:port fails (server down, wrong host/port, firewall, DNS).","commonSituations":"Pointing bd at a company-hosted Dolt server that was stopped or migrated, typos in BEADS_DOLT_SERVER_HOST/PORT, security groups or firewalls blocking the port from this machine.","solutions":["Verify reachability: nc -zv <host> <port> (or curl <host>:<port>)","Run bd dolt status for a detailed external-server check","Start or restart the external Dolt server on the remote host","Correct BEADS_DOLT_SERVER_HOST / BEADS_DOLT_SERVER_PORT (or config.yaml) if they are wrong","If you actually want a local server, remove the external-server configuration (explicit port/shared mode) so auto-start resumes"],"exampleFix":"// before: stale host after server migration\nexport BEADS_DOLT_SERVER_HOST=old-db.internal\n// after: correct host, then verify\nexport BEADS_DOLT_SERVER_HOST=dolt.internal\nnc -zv dolt.internal 31145","handlingStrategy":"validation","validationCode":"host := os.Getenv(\"BEADS_DOLT_SERVER_HOST\")\nport := 31145 // resolved from config\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, strconv.Itoa(port)), 3*time.Second)\nif err != nil {\n    return fmt.Errorf(\"external dolt server %s:%d unreachable: %w\", host, port, err)\n}\nconn.Close()","typeGuard":"func isExternalServerUnreachable(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"will not start a local server because an external one is configured\")\n}","tryCatchPattern":"port, err := doltserver.EnsureRunning(beadsDir)\nif err != nil && isExternalServerUnreachable(err) {\n    // fall back to a local dev server only if policy allows\n    os.Unsetenv(\"BEADS_DOLT_SERVER_HOST\")\n    port, err = doltserver.EnsureRunning(beadsDir)\n}","preventionTips":["Add a health probe (nc -zv host port) to startup scripts before invoking bd","Monitor the external Dolt server's uptime and alerts","Keep BEADS_DOLT_SERVER_HOST/PORT in sync with the server's actual address","Run bd dolt status after any network or DNS change"],"tags":["network","external-server","unreachable","dolt"],"backgroundTag":"connection-refused","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}