{"record":{"id":"ea4a5e3a37088753","repo":"gastownhall/beads","slug":"dolt-server-not-reachable-w","errorCode":null,"errorMessage":"dolt server not reachable: %w","messagePattern":"dolt server not reachable: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor/fix/validation.go","lineNumber":338,"sourceCode":"// Delegates to openFixDB for DSN construction (timeout + password support).\n// Also returns the loaded config so callers that need it afterward (e.g. to\n// verify the connection's target identity) don't have to load it a second\n// time and risk it disagreeing with what was actually dialed.\nfunc openDoltDB(beadsDir string) (*sql.DB, *configfile.Config, error) {\n\tcfg, err := configfile.Load(beadsDir)\n\tif err != nil || cfg == nil {\n\t\treturn nil, nil, fmt.Errorf(\"no database configuration found\")\n\t}\n\n\tdb, err := openFixDB(beadsDir, cfg)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"dolt server connection failed: %w\", err)\n\t}\n\n\t// Verify the connection actually works\n\tif err := db.Ping(); err != nil {\n\t\t_ = db.Close() // Best effort cleanup\n\t\treturn nil, nil, fmt.Errorf(\"dolt server not reachable: %w\", err)\n\t}\n\n\treturn db, cfg, nil\n}\n","sourceCodeStart":320,"sourceCodeEnd":343,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/fix/validation.go#L320-L343","documentation":"openDoltDB opens a SQL connection to the local Dolt server during `bd doctor` fix/validation checks and, after dialing, calls db.Ping() to verify the server actually answers. If the ping fails, it closes the connection and wraps the driver error with this message. It means the TCP listener may exist (the dial succeeded) but the server is not responding to a live handshake/query — or the dial itself failed and the wrapped error carries that detail.","triggerScenarios":"Any of the doctor commands that open the DB (RecomputeBlocked, ScanSeveredCloneLocalFKs, CloneLocalFKEnforcement, DependencyKeys, FixMissingDoltDatabase, OrphanedDependencies) run while the Dolt server process is down, listening on the wrong port/host, still starting up, or rejecting the configured credentials/database.","commonSituations":"The user never ran `dolt sql-server` (or `bd dolt server`) in the repo; the server crashed or was killed; stale config points at a port another (dead) instance used; the server is bound to a socket/port that differs from bd's configuration; firewall or permission issues block localhost connections.","solutions":["Start the Dolt server in the repository (e.g. `bd dolt server` or `dolt sql-server`) and re-run the doctor command.","Verify the server is listening: `dolt sql -q 'select 1'` or check the port with `ss -ltnp`/`lsof -i :<port>`.","Check bd's Dolt connection config (host/port/database in .beads config) matches the running server.","If the server is mid-start, wait and retry; if it repeatedly crashes, inspect the Dolt server logs."],"exampleFix":"// before (server down)\n$ bd doctor fix-missing-dolt-db\ndolt server not reachable: dial tcp 127.0.0.1:3307: connect: connection refused\n\n// after\n$ bd dolt server &\n$ bd doctor fix-missing-dolt-db\nOK","handlingStrategy":"retry","validationCode":"func doltReachable(port int) bool {\n\tconn, err := net.DialTimeout(\"tcp\", fmt.Sprintf(\"127.0.0.1:%d\", port), 2*time.Second)\n\tif err != nil {\n\t\treturn false\n\t}\n\tconn.Close()\n\treturn true\n}\n// call before running doctor fix commands; start the server if false","typeGuard":null,"tryCatchPattern":"db, cfg, err := openDoltDB()\nif err != nil {\n\tvar inner error\n\tif errors.As(err, &inner) && strings.Contains(err.Error(), \"not reachable\") {\n\t\t// surface hint: run `bd dolt server` before retrying\n\t}\n\treturn fmt.Errorf(\"doctor check skipped: %w\", err)\n}","preventionTips":["Run `bd dolt server` (or dolt sql-server) as part of your dev environment startup.","Add a health check (`bd list`) before scripting doctor commands.","Keep host/port configuration in .beads consistent across the team.","Monitor the Dolt server process so crashes are detected early."],"tags":["database","dolt","connectivity","doctor"],"backgroundTag":"dolt-server-unreachable","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}