gastownhall/beads · error

acquire connection for flatten: %w

Error message

acquire connection for flatten: %w

What it means

DoltStore.Flatten needs a single pinned connection from the *sql.DB pool because the DOLT_* stored procedures it invokes (via versioncontrolops.Flatten) depend on session-scoped state. This error wraps a failure to get that connection from the pool. It means Flatten never ran; the underlying driver error is in the wrapped chain.

Source

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

		return nil, fmt.Errorf("acquire connection for remote-ref prune: %w", err)
	}
	defer conn.Close()
	return versioncontrolops.PruneRemoteRefs(ctx, conn)
}

// ListTags returns the names of all Dolt tags.
func (s *DoltStore) ListTags(ctx context.Context) ([]string, error) {
	return versioncontrolops.ListTags(ctx, s.db)
}

// Flatten squashes all Dolt commit history into a single commit.
// Pins a single connection because the stored procedures (DOLT_CHECKOUT,
// DOLT_RESET, etc.) rely on session-scoped state that would be lost if
// steps execute on different pooled connections.
func (s *DoltStore) Flatten(ctx context.Context) error {
	conn, err := s.db.Conn(ctx)
	if err != nil {
		return fmt.Errorf("acquire connection for flatten: %w", err)
	}
	defer conn.Close()
	return versioncontrolops.Flatten(ctx, conn)
}

// Compact squashes old Dolt commits while preserving recent ones.
// Pins a single connection for session-scoped stored procedures.
func (s *DoltStore) Compact(ctx context.Context, initialHash, boundaryHash string, oldCommits int, recentHashes []string) error {
	conn, err := s.db.Conn(ctx)
	if err != nil {
		return fmt.Errorf("acquire connection for compact: %w", err)
	}
	defer conn.Close()
	return versioncontrolops.Compact(ctx, conn, initialHash, boundaryHash, oldCommits, recentHashes)
}

// UnderlyingDB returns the underlying *sql.DB connection
func (s *DoltStore) UnderlyingDB() *sql.DB {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped driver error in errors.Unwrap / %w chain to find the root cause (pool timeout vs context canceled vs connection refused).
2. Audit code paths that call s.db.Conn and confirm defer conn.Close() runs on every path, so the pool is not drained by leaks.
3. Retry Flatten with a fresh, non-canceled context after reducing concurrent DoltStore operations; consider raising the pool size (SetMaxOpenConns).
4. Verify the Dolt server/database is running and reachable if the wrapped error is a network or auth failure.

Example fix

// before
ctx := context.Background() // parent ctx already expired upstream
err := store.Flatten(ctx)
// after
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := store.Flatten(ctx); err != nil {
	log.Printf("flatten failed: %v", err) // inspect wrapped cause
}

// before calling Flatten
select {
case <-ctx.Done():
	return ctx.Err()
default:
}
// ensure pool headroom (informational)
// db.Stats().InUse / db.Stats().MaxOpenConnections

err := store.Flatten(ctx)
var netErr net.Error
if errors.As(err, &netErr) || errors.Is(err, context.DeadlineExceeded) {
	// retry with fresh context/backoff
}

When it happens

Trigger: Calling DoltStore.Flatten when db.Conn(ctx) fails: pool exhausted (all connections checked out), context canceled/deadline exceeded before a connection is available, or the database/driver is unreachable.

Common situations: Long-running concurrent operations leak or hold pinned connections until the pool drains; test harnesses shut the DB down mid-operation; a caller passes an already-canceled context; connection limits on the embedded Dolt server are hit under load.

Related errors

• acquire connection for gc: %w
• acquire connection for remote-ref prune: %w
• acquire connection for compact: %w
• failed to acquire connection: %w
• ErrTransaction

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