{"record":{"id":"c0e7e318e05a96b7","repo":"gastownhall/beads","slug":"no-dolt-server-port-configured-and-no-server-runni","errorCode":null,"errorMessage":"no Dolt server port configured and no server running; run any bd command to auto-start","messagePattern":"no Dolt server port configured and no server running; run any bd command to auto-start","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor/dolt.go","lineNumber":39,"sourceCode":"func openDoltDB(beadsDir string) (*sql.DB, *configfile.Config, error) {\n\tcfg, err := configfile.Load(beadsDir)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to load config: %w\", err)\n\t}\n\tif cfg == nil {\n\t\treturn nil, nil, fmt.Errorf(\"no beads configuration found in %s\", beadsDir)\n\t}\n\n\thost := cfg.GetDoltServerHost()\n\tuser := cfg.GetDoltServerUser()\n\tdatabase := cfg.GetDoltDatabase()\n\n\t// Use doltserver.DefaultConfig for port resolution (env > port file > config.yaml).\n\t// Port 0 means no server running yet.\n\tdsCfg := doltserver.DefaultConfig(beadsDir)\n\tport := dsCfg.Port\n\tif port == 0 {\n\t\treturn nil, nil, fmt.Errorf(\"no Dolt server port configured and no server running; run any bd command to auto-start\")\n\t}\n\n\t// Resolve the password using the credentials file fallback keyed by the\n\t// resolved runtime port — matching the CRUD path. Env var BEADS_DOLT_PASSWORD\n\t// still takes precedence inside GetDoltServerPasswordForPort. Without this,\n\t// externally-hosted Dolt servers that keep credentials in\n\t// ~/.config/beads/credentials fail doctor checks with \"Access denied\" while\n\t// regular CRUD commands succeed (bd-h5k7).\n\tpassword := cfg.GetDoltServerPasswordForPort(port)\n\n\tconnStr := doltutil.ServerDSN{\n\t\tHost:     host,\n\t\tPort:     port,\n\t\tUser:     user,\n\t\tPassword: password,\n\t\tDatabase: database,\n\t\tTLS:      cfg.GetDoltServerTLS(),\n\t}.String()","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/dolt.go#L21-L57","documentation":"After loading config, openDoltDB resolves the Dolt server port via doltserver.DefaultConfig (env var > port file > config.yaml). A port of 0 means no server is currently running and no port was ever recorded. bd doctor does not auto-start the server itself, so it fails fast with guidance to run any bd command, which auto-starts the Dolt server and writes the port file.","triggerScenarios":"Calling openDoltDB (via openDoltConn or querySQLRemotes in `bd doctor`) when dsCfg.Port == 0: no BEADS_DOLT_PORT-style env override, no port file in the beads dir, and no port in config.yaml — i.e., the embedded/remote Dolt server has never been started for this workspace.","commonSituations":"Running `bd doctor` as the very first command in a fresh clone; the server was stopped and the port file was cleaned; port file stale/removed by artifact cleanup; doctor run in a CI container where the server was never launched.","solutions":["Run any bd command (e.g. `bd list`) to auto-start the Dolt server and write the port file, then re-run `bd doctor`.","Check the port file in the .beads directory and, if missing, confirm the server process is expected to run on this machine.","Set the port explicitly via the environment/config if you use an externally hosted Dolt server (env var > port file > config.yaml precedence)."],"exampleFix":"// before\nbd doctor\n// error: no Dolt server port configured and no server running\n// after\nbd list   # auto-starts the Dolt server\nbd doctor","handlingStrategy":"retry","validationCode":"port := doltserver.DefaultConfig(beadsDir).Port\nif port == 0 {\n    // trigger auto-start via any bd command before doctor\n}","typeGuard":null,"tryCatchPattern":"if err := runDoctor(); err != nil && strings.Contains(err.Error(), \"no server running\") {\n    time.Sleep(2 * time.Second) // or run `bd list` to auto-start\n    err = runDoctor()\n}","preventionTips":["Run a normal bd command (bd list) before bd doctor in fresh environments.","Do not delete port files from the .beads directory; let bd manage server lifecycle.","For externally hosted servers, set the port explicitly via env or config.yaml."],"tags":["dolt","server","port","configuration"],"backgroundTag":"server-not-running","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}