gastownhall/beads · error

uow: ping db: %w

Error message

uow: ping db: %w

What it means

openDB verifies the freshly opened connection with conn.PingContext; this error wraps a ping failure and is returned joined with the connection Close error. It is thrown because the Dolt SQL server could not be reached or refused/authenticated the connection — the pool could not establish at least one live connection.

Source

Thrown at internal/storage/uow/dolt_sql_provider.go:387

func buildDSN(ep proxy.Endpoint, database, user, password, tlsConfigName string) string {
	return util.DoltServerDSN{
		Host:            ep.Host,
		Port:            ep.Port,
		User:            user,
		Password:        password,
		Database:        database,
		TLSConfigName:   tlsConfigName,
		ClientFoundRows: true,
	}.String()
}

func openDB(ctx context.Context, dsn string) (*sql.DB, error) {
	conn, err := sql.Open("mysql", dsn)
	if err != nil {
		return nil, fmt.Errorf("uow: open db: %w", err)
	}
	if err := conn.PingContext(ctx); err != nil {
		return nil, errors.Join(fmt.Errorf("uow: ping db: %w", err), conn.Close())
	}
	return conn, nil
}

func openAndInitSchema(ctx context.Context, ep proxy.Endpoint, database, rootUser, rootPassword, tlsConfigName string, teamServer bool, expectedProjectID string, opts providerOptions) (UnitOfWorkProvider, error) {
	initDB, err := openDB(ctx, buildDSN(ep, "", rootUser, rootPassword, tlsConfigName))
	if err != nil {
		return nil, err
	}

	initProvider := &doltSQLProvider{
		defaultBranch:     defaultBranch,
		db:                initDB,
		serverEndpoint:    "tcp:" + ep.Address(),
		teamServer:        teamServer,
		expectedProjectID: expectedProjectID,
		preview:           opts.preview,
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Confirm the Dolt SQL server is running and listening on the configured host:port (e.g. `bd serve` or the embedded server process).
2. Verify endpoint, username, and password in bd configuration match the server.
3. Check network reachability (firewall, Docker networking, localhost vs container hostname) and TLS settings.
4. Re-run after the server restarts — this is a transient connectivity failure, and context timeouts mean the operation may simply have been too slow.
5. Inspect the joined driver error for the exact root cause (connection refused vs access denied vs TLS).

Example fix

// before: server not started, ping fails
$ bd init
// after: start the Dolt SQL server first
$ bd serve &
$ bd init

// Before calling the library: probe the server yourself
func serverUp(addr string) error {
    conn, err := net.DialTimeout("tcp", addr, 3*time.Second)
    if err != nil {
        return fmt.Errorf("dolt server not reachable at %s: %w", addr, err)
    }
    _ = conn.Close()
    return nil
}

func isPingError(err error) bool {
    return err != nil && strings.Contains(err.Error(), "uow: ping db:")
}

p, err := uow.Open(ctx, cfg)
if err != nil {
    if strings.Contains(err.Error(), "uow: ping db:") {
        // transient connectivity: back off and retry
        return retryWithBackoff(ctx, 3, 2*time.Second)
    }
    return err
}

When it happens

Trigger: conn.PingContext(ctx) fails during openAndInitSchema's openDB call — server not listening on endpoint, connection refused, TLS handshake failure, wrong credentials, or the context is cancelled/timed out before the ping completes.

Common situations: Dolt server not started (bd serve / embedded server down); wrong port or host in configuration; firewall or container networking blocking the port; stale server after restart; expired/mismatched TLS config name; rootPassword changed on the server.

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

• server not reachable: %w
• dolt server connection failed: %w
• failed to ping server: %w
• failed to reach the workspace identity: %v
• begin tx: %w

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