gastownhall/beads · error

Configured Dolt server at %s:%d is unreachable, and auto-sta

Error message

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

This is an external server; bd will not start it. Verify it is running:
  nc -zv %s %d  # or curl %s:%d for an HTTP-style check
  bd dolt status   # detailed external-server check

What it means

Defense-in-depth check in EnsureRunningDetailed: if dolt.auto-start is explicitly disabled (config.yaml or BEADS_DOLT_AUTO_START=0), bd never spawns a server even if stale AutoStart=true slipped through. For a non-localhost configured host, this error states that the configured external server is unreachable and bd will not start it — auto-start is off.

Source

Thrown at internal/doltserver/doltserver.go:995

				"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)
		}
		return 0, false, fmt.Errorf("Dolt server unreachable (port %d) and auto-start is disabled "+
			"(dolt.auto-start: false in config.yaml or BEADS_DOLT_AUTO_START=0).\n\n"+
			"Start the server manually or enable auto-start.\n"+
			"  To start manually: bd dolt start\n"+
			"  To check status: bd dolt status", cfg.Port)
	}

	s, err := Start(serverDir)
	if err != nil {
		return 0, false, err
	}
	return s.Port, true, nil

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the external server: nc -zv <host> <port> (or curl <host>:<port>), then bd dolt status
2. Start the external Dolt server on the remote host
3. If bd should manage a local server instead, unset BEADS_DOLT_AUTO_START=0 and remove dolt.auto-start: false
4. Correct BEADS_DOLT_SERVER_HOST/PORT if the configured address is stale

Example fix

// before: auto-start disabled but remote server down
export BEADS_DOLT_AUTO_START=0
export BEADS_DOLT_SERVER_HOST=dolt.internal
// after: start the server, or re-enable auto-start if bd should manage it
unset BEADS_DOLT_AUTO_START
bd dolt start

// Verify the external server before bd needs it, especially when auto-start is off
if os.Getenv("BEADS_DOLT_AUTO_START") == "0" {
    host := os.Getenv("BEADS_DOLT_SERVER_HOST")
    conn, err := net.DialTimeout("tcp", host+":31145", 3*time.Second)
    if err != nil {
        return fmt.Errorf("auto-start disabled and %s unreachable — start it first", host)
    }
    conn.Close()
}

func isAutoStartDisabledUnreachable(err error) bool {
    return err != nil && strings.Contains(err.Error(), "auto-start is disabled") && strings.Contains(err.Error(), "will not start it")
}

port, err := doltserver.EnsureRunning(beadsDir)
if err != nil && isAutoStartDisabledUnreachable(err) {
    // Either bring the external server up, or lift the auto-start block and retry
    os.Unsetenv("BEADS_DOLT_AUTO_START")
    port, err = doltserver.EnsureRunning(beadsDir)
}

When it happens

Trigger: EnsureRunning/EnsureRunningDetailed reaching the IsAutoStartDisabled() branch with externalNonLocalhostHost set and the configured host:port failing the reachability check — e.g. BEADS_DOLT_AUTO_START=0 in the environment plus an unreachable BEADS_DOLT_SERVER_HOST.

Common situations: CI/sandbox environments exporting BEADS_DOLT_AUTO_START=0 while pointing bd at a shared Dolt host that is down or firewalled; stale AutoStart=true in config combined with disabled auto-start env.

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

• Dolt server is not running on port %d, and auto-start is sup
• Dolt server at %s:%d is unreachable, and bd will not start a
• multiple .doltcfg directories detected
• dolt directory is required
• ErrFSCKTimeout

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