gastownhall/beads · error

uow: pin connection: %w

Error message

uow: pin connection: %w

What it means

RunNonTx pins a dedicated connection from the Dolt SQL provider's connection pool via db.Conn(ctx). This error wraps any failure to obtain that connection (e.g. the pool is exhausted, the database is unreachable, or ctx is cancelled before a connection can be acquired), so the caller's fn never runs.

Source

Thrown at internal/storage/uow/maintenance.go:18

package uow

import (
	"context"
	"database/sql"
	"fmt"
)

type MaintenanceProvider interface {
	RunNonTx(ctx context.Context, fn func(ctx context.Context, conn *sql.Conn) error) error
}

var _ MaintenanceProvider = (*doltSQLProvider)(nil)

func (p *doltSQLProvider) RunNonTx(ctx context.Context, fn func(ctx context.Context, conn *sql.Conn) error) error {
	conn, err := p.db.Conn(ctx)
	if err != nil {
		return fmt.Errorf("uow: pin connection: %w", err)
	}
	defer func() { _ = conn.Close() }()
	return fn(ctx, conn)
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check that the Dolt server is running and reachable (try any other bd command)
2. Check for leaked connections/long transactions holding all pool slots; restart the bd process or the server if the pool is wedged
3. Increase or verify context timeouts so connection acquisition is not cut short
4. Retry the command; if it recurs, inspect server logs for connection limits

Example fix

// before
err := bd doctor (fails: uow: pin connection: context deadline exceeded)
// after
bd doctor --timeout 120s  # allow more time to acquire a connection

// Go: check server reachability and give ctx room before the call
if err := pingDatabase(ctx); err != nil { return fmt.Errorf("dolt server unreachable: %w", err) }
ctx, cancel := context.WithTimeout(ctx, 120*time.Second); defer cancel()

func isConnAcquireFailure(err error) bool {
  return err != nil && (errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) || strings.Contains(err.Error(), "pin connection"))
}

err := provider.RunNonTx(ctx, fn)
if errors.Is(err, context.DeadlineExceeded) || isConnAcquireFailure(err) {
  // back off and retry once
  time.Sleep(time.Second); err = provider.RunNonTx(ctx, fn)
}
return err

When it happens

Trigger: Calling any maintenance operation routed through doltSQLProvider.RunNonTx when db.Conn(ctx) fails: pool exhausted (all conns checked out), database server down/unreachable, or ctx deadline/cancellation fires while waiting for a free connection.

Common situations: A long-running transaction or leaked connection exhausted the pool; the Dolt server was restarted or is unreachable; a per-command context timeout (e.g. bd's own timeout flag) expired while queued for a connection; network interruption to a remote dolt server.

Related errors

• dolt server connection failed: %w
• failed to reach the workspace identity: %v
• begin tx: %w
• begin read tx: %w
• begin write tx: %w

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