gastownhall/beads · error

ensure global db: server not reachable: %w

Error message

ensure global db: server not reachable: %w

What it means

EnsureGlobalDatabase wraps db.PingContext failure with this message: the DSN parsed, but no reachable MySQL-protocol server answered at host:port within the 10-second context timeout. This means the dolt sql-server is not running, listening elsewhere, or refusing/dropping connections — the global beads_global database cannot be created.

Source

Thrown at internal/doltserver/doltserver.go:1544

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	dsn := doltutil.ServerDSN{
		Host:     host,
		Port:     port,
		User:     user,
		Password: password,
	}.String()
	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return fmt.Errorf("ensure global db: failed to open connection: %w", err)
	}
	defer db.Close()
	db.SetMaxOpenConns(1)
	db.SetConnMaxLifetime(10 * time.Second)

	if err := db.PingContext(ctx); err != nil {
		return fmt.Errorf("ensure global db: server not reachable: %w", err)
	}

	// CREATE DATABASE IF NOT EXISTS is idempotent — safe on every call.
	// GlobalDatabaseName is a constant ("beads_global"), not user input.
	_, err = db.ExecContext(ctx, fmt.Sprintf("CREATE DATABASE IF NOT EXISTS `%s`", GlobalDatabaseName)) //nolint:gosec // G201: constant database name
	if err != nil {
		errLower := strings.ToLower(err.Error())
		if !strings.Contains(errLower, "database exists") && !strings.Contains(errLower, "1007") {
			return fmt.Errorf("ensure global db: failed to create %s: %w", GlobalDatabaseName, err)
		}
	}

	return nil
}

// FlushWorkingSet connects to the running Dolt server and commits any uncommitted
// working set changes across all databases. This prevents data loss when the server
// is about to be stopped or restarted. Returns nil if there's nothing to flush or

View on GitHub (pinned to 71377f2769)

Solutions

1. Confirm the server is up: bd dolt status, or nc -vz <host> <port>; start it with bd dolt start if down
2. Verify host/port/credentials in bd config / BEADS_DB_HOST / BEADS_DB_PORT match the actual server
3. Read the wrapped error: 'connection refused' = wrong port or dead server; 'timeout' = firewall/routing; 'access denied' = wrong user/password
4. Check container/network reachability (docker network, VPN, security groups) if the server runs remotely
5. If the server is up but slow, investigate server load — the ping window is fixed at 10s

Example fix

// before
// error: ensure global db: server not reachable: dial tcp 10.0.0.5:3307: connect: connection refused
// after: point config at the live server (or start it)
// $ bd dolt start
// $ bd config set dolt.shared-server-host 10.0.0.5
// $ bd config set dolt.shared-server-port 3308

// Reachability pre-check before EnsureGlobalDatabase
conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(port)), 3*time.Second)
if err != nil {
    return fmt.Errorf("dolt server not listening on %s:%d — run bd dolt start", host, port)
}
conn.Close()

err := doltserver.EnsureGlobalDatabase(host, port, user, password)
if err != nil && strings.Contains(err.Error(), "server not reachable") {
    // one bounded retry after a short wait — server may still be starting
    time.Sleep(2 * time.Second)
    if retryErr := doltserver.EnsureGlobalDatabase(host, port, user, password); retryErr != nil {
        return fmt.Errorf("ensure global db failed (is the server up? bd dolt status): %w", retryErr)
    }
    return nil
}
if err != nil { return err }
return nil

When it happens

Trigger: db.PingContext(ctx) returns an error on a freshly opened connection to the shared dolt server — server never started or already exited, wrong host/port configuration, connection refused, auth rejected, TLS mismatch, or the 10s ctx deadline elapsed first.

Common situations: Shared server managed by systemd crashed or was never started; another developer's server on a different port in BEADS_DB_PORT; Docker network/hostname misconfiguration; firewall blocking the port; wrong password in shared config; server overloaded and not accepting within 10s.

Related errors

• dolt server unreachable at %s:%d (is dolt sql-server running
• failed to ping server: %w
• flush: server not reachable: %w
• failed to remove backup: %w
• server not reachable: %w

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