gastownhall/beads · error

acquire connection for checkout: %w

Error message

acquire connection for checkout: %w

What it means

Checkout requires a dedicated pooled connection so the Dolt session's branch context is consistent. This wraps a failure from s.db.Conn(ctx) when acquiring the connection used by versioncontrolops.CheckoutBranch. Same mechanics as pool acquisition failures everywhere: exhausted pool, cancelled context, or dead backend.

Source

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

	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)
	}
	defer conn.Close()
	if err := versioncontrolops.CheckoutBranch(ctx, conn, branch); err != nil {
		return err
	}
	s.branch = branch
	return nil
}

// Merge merges the specified branch into the current branch.
// Returns any merge conflicts if present. Implements storage.VersionedStorage.
func (s *DoltStore) Merge(ctx context.Context, branch string) (conflicts []storage.Conflict, retErr error) {
	ctx, span := doltTracer.Start(ctx, "dolt.merge",
		trace.WithSpanKind(trace.SpanKindClient),
		trace.WithAttributes(append(s.doltSpanAttrs(),
			attribute.String("dolt.merge_branch", branch),
		)...),
	)

View on GitHub (pinned to 71377f2769)

Solutions

1. Release other pinned connections (close rows, conns, txs) before checkout.
2. Raise MaxOpenConns or serialize branch operations.
3. Verify ctx is alive before calling checkout; use a fresh context for control-plane operations.
4. Check Dolt server availability and pool health (db.Ping).
5. Retry the checkout; stale connections are evicted from the pool.

if err := ctx.Err(); err != nil { return err }
if err := db.PingContext(ctx); err != nil { return err }

conn, err := s.db.Conn(ctx)
if err != nil {
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
        return fmt.Errorf("checkout cancelled waiting for connection: %w", err)
    }
    return fmt.Errorf("acquire connection for checkout: %w", err)
}
defer conn.Close()

When it happens

Trigger: Calling the store's checkout method (traced with dolt.branch attribute) when s.db.Conn(ctx) returns an error before CheckoutBranch runs — pool exhausted (notably MaxOpenConns:1 with another pinned connection), ctx expired waiting in the pool queue, or the Dolt server is down.

Common situations: Concurrent vc checkout/merge commands under a single-connection pool; watchdog-killed long requests whose context expires mid-wait; server maintenance windows.

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/4eef9b8abea7123f. Report an issue: GitHub.