gastownhall/beads · error

acquire connection for branch: %w

Error message

acquire connection for branch: %w

What it means

CreateBranch needs its own connection from the sql.DB pool (so Dolt session variables like branch state stay pinned). This error wraps database/sql's (*sql.DB).Conn failure when acquiring that connection for branch creation. It means the pool could not hand out a connection: pool exhausted, all connections stale, context done, or the database is unreachable.

Source

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

// when (repaired=false, had=true) — unrepaired violations are the operator's.
// The implementation is shared with the embedded pull path (bd-6dnrw.40); see
// versioncontrolops.TryRepairFKCascadeViolations for the full contract.
func (s *DoltStore) tryRepairFKCascadeViolations(ctx context.Context, tx *sql.Tx) (repaired, had bool, err error) {
	return versioncontrolops.TryRepairFKCascadeViolations(ctx, tx)
}

// Branch creates a new branch
func (s *DoltStore) Branch(ctx context.Context, name string) (retErr error) {
	ctx, span := doltTracer.Start(ctx, "dolt.branch",
		trace.WithSpanKind(trace.SpanKindClient),
		trace.WithAttributes(append(s.doltSpanAttrs(),
			attribute.String("dolt.branch", name),
		)...),
	)
	defer func() { endSpan(span, retErr) }()
	conn, err := s.db.Conn(ctx)
	if err != nil {
		return fmt.Errorf("acquire connection for branch: %w", err)
	}
	defer conn.Close()
	return versioncontrolops.CreateBranch(ctx, conn, name)
}

// Checkout switches to the specified branch
func (s *DoltStore) Checkout(ctx context.Context, branch string) (retErr error) {
	ctx, span := doltTracer.Start(ctx, "dolt.checkout",
		trace.WithSpanKind(trace.SpanKindClient),
		trace.WithAttributes(append(s.doltSpanAttrs(),
			attribute.String("dolt.branch", branch),
		)...),
	)
	defer func() { endSpan(span, retErr) }()
	conn, err := s.db.Conn(ctx)
	if err != nil {
		return fmt.Errorf("acquire connection for checkout: %w", err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Ensure preceding operations release their connections/transactions before creating a branch.
2. Increase MaxOpenConns in the pool configuration if concurrency demands it.
3. Check ctx deadline — waiting for a free connection is cancelled by expired contexts.
4. Ping the Dolt server / restart it if all pooled connections are dead.
5. Retry; database/sql will prune bad connections from the pool on subsequent attempts.

Example fix

// before
db.SetMaxOpenConns(1) // branch creation starves while another conn is held
// after
db.SetMaxOpenConns(4)
db.SetConnMaxLifetime(5 * time.Minute)

if err := ctx.Err(); err != nil { return err }
stats := db.Stats()
if stats.MaxOpenConnections > 0 && stats.InUse >= stats.MaxOpenConnections { return errors.New("connection pool exhausted") }

conn, err := s.db.Conn(ctx)
if err != nil {
    var waited bool
    if errors.Is(err, context.DeadlineExceeded) { waited = true }
    return fmt.Errorf("acquire connection for branch (waited=%v): %w", waited, err)
}

When it happens

Trigger: Calling the store's branch-creation method (traced with dolt.branch attribute) when s.db.Conn(ctx) fails — pool at MaxOpenConns with all connections busy (e.g. MaxOpenConns:1 and another operation holds the connection), or ctx cancelled while waiting for a free connection.

Common situations: Test setups or constrained production configs with MaxOpenConns:1 where a prior operation didn't release its connection; long queue of concurrent vc branch calls; Dolt server restart leaving dead pooled connections.

Related errors

• iter dependents: acquire conn: %w
• checkout active branch %q: %w
• failed to rebuild pool after migration: %w
• acquire connection for gc: %w
• acquire connection for remote-ref prune: %w

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