{"record":{"id":"1a42c2f2a4824c5a","repo":"gastownhall/beads","slug":"server-not-reachable-w","errorCode":null,"errorMessage":"server not reachable: %w","messagePattern":"server not reachable: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor/dolt.go","lineNumber":74,"sourceCode":"\t\tTLS:      cfg.GetDoltServerTLS(),\n\t}.String()\n\n\tdb, err := sql.Open(\"mysql\", connStr)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to open server connection: %w\", err)\n\t}\n\n\tdb.SetMaxOpenConns(2)\n\tdb.SetMaxIdleConns(1)\n\tdb.SetConnMaxLifetime(30 * time.Second)\n\n\t// Verify connectivity\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\tif err := db.PingContext(ctx); err != nil {\n\t\t_ = db.Close() // Best effort cleanup\n\t\treturn nil, nil, fmt.Errorf(\"server not reachable: %w\", err)\n\t}\n\n\treturn db, cfg, nil\n}\n\n// doltConn holds an open Dolt connection.\n// Used by doctor checks to coordinate database access.\ntype doltConn struct {\n\tdb   *sql.DB\n\tcfg  *configfile.Config // config for server detail (host:port)\n\tport int                // resolved port (from doltserver.DefaultConfig, not cfg fallback)\n}\n\n// Close releases the database connection.\nfunc (c *doltConn) Close() {\n\t_ = c.db.Close()\n}\n","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/dolt.go#L56-L92","documentation":"After sql.Open succeeds, openDoltDB verifies the Dolt server is actually reachable with a 5-second-timeout PingContext, closing the DB handle on failure. This error wraps the ping failure, so the wrapped error contains the real cause: connection refused, timeout, auth failure, TLS mismatch, or unknown database.","triggerScenarios":"Calling openDoltDB (via openDoltConn or querySQLRemotes) when db.PingContext fails within 5s: the Dolt server is not listening on the resolved port, it just crashed or is still starting, credentials are wrong, TLS is required/mismatched, or the configured database does not exist on the server.","commonSituations":"Stale port file pointing at a port where the server no longer listens; server still booting after auto-start (race); wrong password in credentials file vs BEADS_DOLT_PASSWORD env; externally hosted server with TLS config mismatch; firewall blocking localhost/remote port.","solutions":["Confirm the server is running and the resolved port is correct: check the port file in the .beads dir and the server process/log; restart via any bd command.","Inspect the wrapped %w error for the exact cause (connection refused vs. timeout vs. \"Access denied\" vs. \"Unknown database\") and fix accordingly — credentials, database name, or TLS settings in config.yaml.","Increase tolerance for slow startup by retrying `bd doctor` after a few seconds if the server was just auto-started."],"exampleFix":"// before\nbd doctor\n// error: server not reachable: dial tcp 127.0.0.1:32111: connect: connection refused\n// after\nbd list   # restarts the Dolt server on the correct port\nbd doctor","handlingStrategy":"retry","validationCode":"dsCfg := doltserver.DefaultConfig(beadsDir)\nconn, err := net.DialTimeout(\"tcp\", fmt.Sprintf(\"%s:%d\", dsCfg.Host, dsCfg.Port), 2*time.Second)\nif err != nil {\n    return fmt.Errorf(\"dolt server not listening on %s:%d; run any bd command\", dsCfg.Host, dsCfg.Port)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"db, err := openDoltDB(beadsDir)\nif err != nil && strings.Contains(err.Error(), \"server not reachable\") {\n    var netErr net.Error\n    if errors.As(err, &netErr) && netErr.Timeout() {\n        // retry after allowing server startup\n    }\n    return err\n}","preventionTips":["Retry once with a short delay after auto-starting the server; startup can lag the port file write.","Verify credentials (BEADS_DOLT_PASSWORD or credentials file) match the server for the resolved port.","Confirm TLS settings in config.yaml match the externally hosted server's requirements."],"tags":["dolt","network","ping","timeout","connection"],"backgroundTag":"connection-refused","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}