no Dolt server port configured and no server running; run an

Error message

no Dolt server port configured and no server running; run any bd command to auto-start

What it means

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.

Source

Thrown at cmd/bd/doctor/dolt.go:39

func openDoltDB(beadsDir string) (*sql.DB, *configfile.Config, error) {
	cfg, err := configfile.Load(beadsDir)
	if err != nil {
		return nil, nil, fmt.Errorf("failed to load config: %w", err)
	}
	if cfg == nil {
		return nil, nil, fmt.Errorf("no beads configuration found in %s", beadsDir)
	}

	host := cfg.GetDoltServerHost()
	user := cfg.GetDoltServerUser()
	database := cfg.GetDoltDatabase()

	// Use doltserver.DefaultConfig for port resolution (env > port file > config.yaml).
	// Port 0 means no server running yet.
	dsCfg := doltserver.DefaultConfig(beadsDir)
	port := dsCfg.Port
	if port == 0 {
		return nil, nil, fmt.Errorf("no Dolt server port configured and no server running; run any bd command to auto-start")
	}

	// Resolve the password using the credentials file fallback keyed by the
	// resolved runtime port — matching the CRUD path. Env var BEADS_DOLT_PASSWORD
	// still takes precedence inside GetDoltServerPasswordForPort. Without this,
	// externally-hosted Dolt servers that keep credentials in
	// ~/.config/beads/credentials fail doctor checks with "Access denied" while
	// regular CRUD commands succeed (bd-h5k7).
	password := cfg.GetDoltServerPasswordForPort(port)

	connStr := doltutil.ServerDSN{
		Host:     host,
		Port:     port,
		User:     user,
		Password: password,
		Database: database,
		TLS:      cfg.GetDoltServerTLS(),
	}.String()

View on GitHub (pinned to 71377f2769)

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).

Example fix

// before
bd doctor
// error: no Dolt server port configured and no server running
// after
bd list   # auto-starts the Dolt server
bd doctor

Defensive patterns

Strategy: retry

Validate before calling

port := doltserver.DefaultConfig(beadsDir).Port
if port == 0 {
    // trigger auto-start via any bd command before doctor
}

Try / catch

if err := runDoctor(); err != nil && strings.Contains(err.Error(), "no server running") {
    time.Sleep(2 * time.Second) // or run `bd list` to auto-start
    err = runDoctor()
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/c0e7e318e05a96b7. Report an issue: GitHub.