dolt sql-server is not running on %s:%d; start it with 'bd d

Error message

dolt sql-server is not running on %s:%d; start it with 'bd dolt start'

What it means

The Dolt perf diagnostics run through a live dolt sql-server. If the server was not detected running at the configured host:port, the run aborts with this message telling the user how to start it.

Source

Thrown at cmd/bd/doctor/perf_dolt.go:91

	dbName := configfile.DefaultDoltDatabase
	if cfg, err := configfile.Load(beadsDir); err == nil && cfg != nil {
		dbName = cfg.GetDoltDatabase()
	}

	// Start profiling if requested
	if enableProfiling {
		profilePath := fmt.Sprintf("beads-dolt-perf-%s.prof", time.Now().Format("2006-01-02-150405"))
		if profileFile, err := startCPUProfile(profilePath); err != nil {
			fmt.Fprintf(os.Stderr, "Warning: failed to start CPU profiling: %v\n", err)
		} else {
			metrics.ProfilePath = profilePath
			defer stopCPUProfile(profileFile)
		}
	}

	// Connect and run diagnostics via server
	if !serverRunning {
		return metrics, fmt.Errorf("dolt sql-server is not running on %s:%d; start it with 'bd dolt start'", dsCfg.Host, dsCfg.Port)
	}

	if err := runDoltServerDiagnostics(metrics, dsCfg.Host, dsCfg.Port, dbName, beadsDir); err != nil {
		return metrics, fmt.Errorf("server diagnostics failed: %w", err)
	}

	// Calculate database size
	metrics.DatabaseSize = getDoltDatabaseSize(doltDir)

	return metrics, nil
}

// runDoltServerDiagnostics runs diagnostics via dolt sql-server
func runDoltServerDiagnostics(metrics *DoltPerfMetrics, host string, port int, dbName string, beadsDir string) error {
	metrics.Backend = "dolt-server"
	metrics.ServerMode = true

	// Resolve credentials from config and environment, matching openDoltDB behavior.

View on GitHub (pinned to 71377f2769)

Solutions

Run 'bd dolt start' to launch dolt sql-server
Verify the server is listening: check the configured host and port (e.g. ss -ltn / nc -zv host port)
Correct the Dolt server host/port in beads config if pointing at the wrong instance

Example fix

// before
RunDoltPerformanceDiagnostics(path, true) // server not started
// after
exec.Command("bd", "dolt", "start").Run() // then
RunDoltPerformanceDiagnostics(path, true)

Defensive patterns

Strategy: retry

Validate before calling

conn, err := net.DialTimeout("tcp", fmt.Sprintf("%s:%d", host, port), 2*time.Second)
if conn != nil { conn.Close() } // if err != nil, start the server first

Try / catch

if err != nil && strings.Contains(err.Error(), "is not running") {
    exec.Command("bd", "dolt", "start").Run()
    err = RunDoltPerformanceDiagnostics(path, true) // retry once
}

Prevention

Start 'bd dolt start' before any server-based doctor checks
Health-check the host:port in CI before running diagnostics
Publish/expose the Dolt port when running in containers

When it happens

Trigger: RunDoltPerformanceDiagnostics executes with serverRunning == false for the configured DoltServerConfig — dolt sql-server is not listening on dsCfg.Host:dsCfg.Port.

Common situations: Forgot to run 'bd dolt start' after reboot; server crashed; connecting from a different container/host where the port isn't published; wrong host/port in config; embedded vs server mode confusion.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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