{"record":{"id":"4a5daedcc38a3a12","repo":"gastownhall/beads","slug":"configured-dolt-server-at-s-d-is-unreachable-an","errorCode":null,"errorMessage":"Configured Dolt server at %s:%d is unreachable, and auto-start is disabled (dolt.auto-start: false in config.yaml or BEADS_DOLT_AUTO_START=0).\n\nThis is an external server; bd will not start it. Verify it is running:\n  nc -zv %s %d  # or curl %s:%d for an HTTP-style check\n  bd dolt status   # detailed external-server check","messagePattern":"Configured Dolt server at (.+?):(.+?) is unreachable, and auto-start is disabled \\(dolt\\.auto-start: false in config\\.yaml or BEADS_DOLT_AUTO_START=0\\)\\.\n\nThis is an external server; bd will not start it\\. Verify it is running:\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":995,"sourceCode":"\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)\n\t\t}\n\t\treturn 0, false, fmt.Errorf(\"Dolt server unreachable (port %d) and auto-start is disabled \"+\n\t\t\t\"(dolt.auto-start: false in config.yaml or BEADS_DOLT_AUTO_START=0).\\n\\n\"+\n\t\t\t\"Start the server manually or enable auto-start.\\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\ts, err := Start(serverDir)\n\tif err != nil {\n\t\treturn 0, false, err\n\t}\n\treturn s.Port, true, nil","sourceCodeStart":977,"sourceCodeEnd":1013,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L977-L1013","documentation":"Defense-in-depth check in EnsureRunningDetailed: if dolt.auto-start is explicitly disabled (config.yaml or BEADS_DOLT_AUTO_START=0), bd never spawns a server even if stale AutoStart=true slipped through. For a non-localhost configured host, this error states that the configured external server is unreachable and bd will not start it — auto-start is off.","triggerScenarios":"EnsureRunning/EnsureRunningDetailed reaching the IsAutoStartDisabled() branch with externalNonLocalhostHost set and the configured host:port failing the reachability check — e.g. BEADS_DOLT_AUTO_START=0 in the environment plus an unreachable BEADS_DOLT_SERVER_HOST.","commonSituations":"CI/sandbox environments exporting BEADS_DOLT_AUTO_START=0 while pointing bd at a shared Dolt host that is down or firewalled; stale AutoStart=true in config combined with disabled auto-start env.","solutions":["Verify the external server: nc -zv <host> <port> (or curl <host>:<port>), then bd dolt status","Start the external Dolt server on the remote host","If bd should manage a local server instead, unset BEADS_DOLT_AUTO_START=0 and remove dolt.auto-start: false","Correct BEADS_DOLT_SERVER_HOST/PORT if the configured address is stale"],"exampleFix":"// before: auto-start disabled but remote server down\nexport BEADS_DOLT_AUTO_START=0\nexport BEADS_DOLT_SERVER_HOST=dolt.internal\n// after: start the server, or re-enable auto-start if bd should manage it\nunset BEADS_DOLT_AUTO_START\nbd dolt start","handlingStrategy":"validation","validationCode":"// Verify the external server before bd needs it, especially when auto-start is off\nif os.Getenv(\"BEADS_DOLT_AUTO_START\") == \"0\" {\n    host := os.Getenv(\"BEADS_DOLT_SERVER_HOST\")\n    conn, err := net.DialTimeout(\"tcp\", host+\":31145\", 3*time.Second)\n    if err != nil {\n        return fmt.Errorf(\"auto-start disabled and %s unreachable — start it first\", host)\n    }\n    conn.Close()\n}","typeGuard":"func isAutoStartDisabledUnreachable(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"auto-start is disabled\") && strings.Contains(err.Error(), \"will not start it\")\n}","tryCatchPattern":"port, err := doltserver.EnsureRunning(beadsDir)\nif err != nil && isAutoStartDisabledUnreachable(err) {\n    // Either bring the external server up, or lift the auto-start block and retry\n    os.Unsetenv(\"BEADS_DOLT_AUTO_START\")\n    port, err = doltserver.EnsureRunning(beadsDir)\n}","preventionTips":["Health-check external Dolt hosts in CI before running bd","Don't export BEADS_DOLT_AUTO_START=0 globally; scope it to sandboxes that provide their own server","Keep auto-start settings and server address consistent in one place (config.yaml)","Alert on the external Dolt server so outages are caught before bd runs"],"tags":["external-server","auto-start","unreachable","configuration","dolt"],"backgroundTag":"connection-refused","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}