gastownhall/beads · error

failed to open Dolt server connection

Error message

failed to open Dolt server connection: %w

What it means

openServerConnection establishes the main pooled connection to a remote Dolt server via sql.Open("mysql", connStr). This error wraps sql.Open failure when creating the server connection; it indicates driver/config problems at the very start of server-mode open.

Solutions

1. Validate the DSN produced from cfg (host, port, database, credentials)
2. Ensure the mysql driver is imported in the binary
3. Fix config values in metadata.json / flags and retry open
4. Run bd dolt status to cross-check connection settings

Example fix

// before
cfg.ServerHost = "localhost:not-a-port"
// after
cfg.ServerHost = "localhost"
cfg.ServerPort = 3307

connStr := buildServerDSN(cfg, cfg.Database)
if _, err := mysql.ParseDSN(connStr); err != nil {
    return fmt.Errorf("server DSN invalid: %w", err)
}

store, err := OpenStore(ctx, cfg)
if err != nil {
    if strings.Contains(err.Error(), "failed to open Dolt server connection") {
        // inspect cfg host/port/database before retry
    }
    return err
}

When it happens

Trigger: Opening a store in server mode where buildServerDSN(cfg, cfg.Database) yields a DSN that sql.Open rejects (driver missing, malformed DSN).

Common situations: Misconfigured server host/port producing an invalid DSN; mysql driver not linked; corrupted config values interpolated into the DSN.

Related errors

• uow: open db
• acquire connection after SQL mutation
• begin read tx
• begin tx
• begin write tx

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

Appendix: source

Thrown at internal/storage/dolt/store.go:2371

	// alreadyExisted reports whether the database was proven to exist on the
	// server before this call: either the SHOW DATABASES probe found it, or
	// our CREATE DATABASE was refused with "database exists" (1007). Callers
	// use it to decide whether project-identity verification applies even
	// when CreateIfMissing is true (see the newServerMode gate around
	// verifyProjectIdentity, GH#4637).
	alreadyExisted bool
}

// openServerConnection connects to (and if needed creates) the target database
// on a dolt sql-server via MySQL protocol. See serverConnFacts for what the
// returned facts mean and why they are not a single bool.
func openServerConnection(ctx context.Context, cfg *Config) (*sql.DB, string, serverConnFacts, error) {
	connStr := buildServerDSN(cfg, cfg.Database)

	db, err := sql.Open("mysql", connStr)
	if err != nil {
		return nil, "", serverConnFacts{}, fmt.Errorf("failed to open Dolt server connection: %w", err)
	}

	// Configure the pool. *sql.DB is safe for concurrent use and manages its
	// own pool — the same Store reuses these connections across every query
	// for the lifetime of the daemon, rather than opening a fresh one each
	// time (which used to show up as endless NewConnection/ConnectionClosed
	// pairs in dolt-server.log).
	applyPoolLimits(db, cfg)

	// Close the pool on any failure path below; cleared at the success return.
	connReady := false
	defer func() {
		if !connReady {
			_ = db.Close()
		}
	}()

	// A gateway server owns database routing and existence, so bd does not probe or create

View on GitHub (pinned to 71377f2769)