gastownhall/beads · error

failed to open Dolt server connection: %w

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.

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)

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: %w
• database %q not found on Dolt server at %s:%d
• no database connection available (%s)
• failed to open database: %w Hint: %s
• dolt server connection failed: %w

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