gastownhall/beads · error

dolt server unreachable at %s:%d (is dolt sql-server running

Error message

dolt server unreachable at %s:%d (is dolt sql-server running?): %w

What it means

Wrapped by cloneViaServer in cmd/bd/bootstrap.go:969 when db.PingContext fails within a 5-minute timeout, meaning the external Dolt sql-server at the configured host:port did not accept the connection. bd explicitly reports the address and asks whether `dolt sql-server` is running, since clone via server mode depends entirely on a live server.

Source

Thrown at cmd/bd/bootstrap.go:969

		Host:     cfg.GetDoltServerHost(),
		Port:     port,
		User:     cfg.GetDoltServerUser(),
		Password: cfg.GetDoltServerPasswordForPort(port),
		TLS:      cfg.GetDoltServerTLS(),
		// No Database — DOLT_CLONE creates the database.
	}.String()

	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return fmt.Errorf("connect to dolt server for clone: %w", err)
	}
	defer db.Close()

	cloneCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
	defer cancel()

	if err := db.PingContext(cloneCtx); err != nil {
		return fmt.Errorf("dolt server unreachable at %s:%d (is dolt sql-server running?): %w",
			cfg.GetDoltServerHost(), port, err)
	}

	if err := versioncontrolops.DoltClone(cloneCtx, db, remoteURL, dbName, os.Getenv("DOLT_REMOTE_USER")); err != nil {
		return fmt.Errorf("clone from remote via server: %w", err)
	}
	fmt.Fprintf(os.Stderr, "Synced database from %s (via server at %s:%d)\n",
		remoteURL, cfg.GetDoltServerHost(), port)
	return nil
}

func serverClonePort(beadsDir string, cfg *configfile.Config) int {
	if cfg != nil && cfg.DoltServerPort > 0 {
		return cfg.DoltServerPort
	}
	if p := os.Getenv("BEADS_DOLT_SERVER_PORT"); p != "" {
		if port, err := strconv.Atoi(p); err == nil && port > 0 {
			return port

View on GitHub (pinned to 71377f2769)

Solutions

1. Start the Dolt server: run `dolt sql-server` in the server data directory (or bd's owned-server flow)
2. Verify the server address matches config: check dolt_server host/port in .beads/metadata.json and BEADS_DOLT_SERVER_PORT env
3. Test connectivity manually: `mysql -h <host> -P <port> -u <user> -p` or `dolt sql -q 'select 1'` against the server
4. Check firewalls/security groups if the server is remote; confirm the socket path exists if using socket mode

Example fix

// before
$ bd bootstrap
// error: dolt server unreachable at localhost:3307 (is dolt sql-server running?)
// after
$ cd ~/beads-server && dolt sql-server &
$ sleep 2 && bd bootstrap   # Synced database from ... (via server at localhost:3307)

// probe the server before attempting clone
host, port := "localhost", 3307
conn, err := net.DialTimeout("tcp", fmt.Sprintf("%s:%d", host, port), 3*time.Second)
if err != nil { return fmt.Errorf("start dolt sql-server first: %w", err) }
conn.Close()

err := cloneViaServer(ctx, dir, url, db, cfg)
var netErr net.Error
if err != nil && errors.As(err, &netErr) {
	// server unreachable: start/restart dolt sql-server, wait, retry with backoff
	time.Sleep(5 * time.Second)
	err = cloneViaServer(ctx, dir, url, db, cfg)
}

When it happens

Trigger: External-server clone mode is selected but the server is not started, listening on a different port/socket than configured, rejecting credentials, or the network/firewall blocks the host:port.

Common situations: Forgot to start `dolt sql-server --data-dir ...` after reboot; port mismatch (BEADS_DOLT_SERVER_PORT vs actual server port); server bound to localhost while bd uses a container hostname; firewall/security-group blocking the port; wrong password causing access-denied inside the ping.

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 connection failed: %w
• ensure global db: server not reachable: %w
• failed to open server connection: %w
• server not reachable: %w
• failed to ping server: %w

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