Dolt server is not running on port %d, and auto-start is sup

Error message

Dolt server is not running on port %d, and auto-start is suppressed because the server is externally managed (dolt.auto-start: false or explicit port configured).

Start the external server, or enable auto-start to allow bd to manage the server.
  To start manually: bd dolt start
  To check status: bd dolt status

What it means

In External server mode on a localhost-style configuration, EnsureRunningDetailed suppresses auto-start because the server is externally managed (dolt.auto-start disabled or an explicit port configured). If the server is not running, this error tells the operator to start it manually or re-enable auto-start, instead of bd silently spawning a competing local server.

Source

Thrown at internal/doltserver/doltserver.go:982

	}

	// If the server mode is External (explicit port in metadata.json,
	// shared server mode, etc.), do not start a per-project server —
	// it would conflict with the external one.
	mode := ResolveServerMode(beadsDir)
	if mode == ServerModeExternal {
		cfg := DefaultConfig(beadsDir)
		if host, ok := externalNonLocalhostHost(beadsDir); ok {
			// Configured for a non-localhost external server:
			// "bd dolt start" is not the right advice (GH#3518).
			return 0, false, fmt.Errorf("Dolt server at %s:%d is unreachable, and bd will not "+
				"start a local server because an external one is configured.\n\n"+
				"Verify the external server is running and reachable from this host:\n"+
				"  nc -zv %s %d  # or curl %s:%d for an HTTP-style check\n"+
				"  bd dolt status   # detailed external-server check",
				host, cfg.Port, host, cfg.Port, host, cfg.Port)
		}
		return 0, false, fmt.Errorf("Dolt server is not running on port %d, and auto-start is suppressed "+
			"because the server is externally managed (dolt.auto-start: false or explicit port configured).\n\n"+
			"Start the external server, or enable auto-start to allow bd to manage the server.\n"+
			"  To start manually: bd dolt start\n"+
			"  To check status: bd dolt status", cfg.Port)
	}

	// Defense-in-depth: if dolt.auto-start is explicitly disabled in
	// config.yaml or env, never spawn a server even if the caller
	// somehow reached this point (e.g. stale AutoStart=true in config).
	if IsAutoStartDisabled() {
		cfg := DefaultConfig(beadsDir)
		if host, ok := externalNonLocalhostHost(beadsDir); ok {
			return 0, false, fmt.Errorf("Configured Dolt server at %s:%d is unreachable, and auto-start "+
				"is disabled (dolt.auto-start: false in config.yaml or BEADS_DOLT_AUTO_START=0).\n\n"+
				"This is an external server; bd will not start it. Verify it is running:\n"+
				"  nc -zv %s %d  # or curl %s:%d for an HTTP-style check\n"+
				"  bd dolt status   # detailed external-server check",
				host, cfg.Port, host, cfg.Port, host, cfg.Port)

View on GitHub (pinned to 71377f2769)

Solutions

Start the external server manually: bd dolt start
Re-enable auto-start (remove dolt.auto-start: false from config.yaml or unset BEADS_DOLT_AUTO_START=0) so bd manages the server again
Check current state with bd dolt status
If the explicit port was set unintentionally, clear it so bd falls back to managed auto-start

Example fix

// before: config.yaml
auto-start: false
// after: let bd manage the server
auto-start: true
# or run manually: bd dolt start

Defensive patterns

Strategy: fallback

Validate before calling

// Check server is up or auto-start allowed before calling
port, _ := doltserver.EnsureRunning(beadsDir) // probe via IsRunning instead:
state, err := doltserver.IsRunning(serverDir)
if err != nil || !state.Running {
    // either run `bd dolt start` first or ensure auto-start is enabled in config
}

Type guard

func isAutoStartSuppressed(err error) bool {
    return err != nil && strings.Contains(err.Error(), "auto-start is suppressed")
}

Try / catch

port, err := doltserver.EnsureRunning(beadsDir)
if err != nil && isAutoStartSuppressed(err) {
    if out, runErr := exec.Command("bd", "dolt", "start").CombinedOutput(); runErr != nil {
        return fmt.Errorf("manual start failed: %v: %s", runErr, out)
    }
    port, err = doltserver.EnsureRunning(beadsDir)
}

Prevention

Run bd dolt start after reboots when auto-start is disabled
Don't set explicit ports unless you also manage server lifecycle
Keep dolt.auto-start: true for single-user local workflows
Document the external-management contract for your team's machines

When it happens

Trigger: EnsureRunning/EnsureRunningDetailed(beadsDir) where ResolveServerMode==ServerModeExternal with a localhost host (or no non-localhost host), the PID file says not-running, and auto-start is suppressed due to dolt.auto-start: false or an explicitly configured port.

Common situations: User set an explicit port in config.yaml expecting bd to still manage the server, or disabled auto-start earlier and forgot; then ran bd after a reboot without running bd dolt start.

Related errors

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