agent failed to access the data warehouse: connection pool exhausted

TL;DR

Pool exhaustion is usually a leak wearing a load costume: code paths that check out connections and return them only on success slowly strand the pool until every new request waits and dies. Find the leak by watching pool occupancy during a run, fix checkout discipline with guaranteed release, then size the pool to the warehouse's real concurrency.

agent failed to access the data warehouse: connection pool exhausted

Use this when

• Pool wait or checkout timeout errors appear during agent runs
• Occupancy climbs during a run and never recovers
• Long runs fail more than short ones

Not for this skill when

• Many parallel agents legitimately exceed a correctly managed pool
• The warehouse's own connection limit is the binding constraint

Steps

1. Graph pool occupancy and active queries through one failing run. Verify: occupancy growth without release is visible, or exonerated
2. Audit the code paths that check out connections, especially error and early-return branches. Verify: the path that strands connections is found
3. Wrap all checkouts in guaranteed-release blocks and add a checkout timeout with a clear error. Verify: a leak-injection test now fails fast instead of draining the pool
4. Size the pool from measured concurrent query needs and the warehouse's per-user limits. Verify: pool size is set from evidence and within warehouse limits
5. Add pool occupancy alerting so exhaustion approaches are seen before failures. Verify: the next leak or load shift warns early

Variant phrasings

agent warehouse connection pool exhausted

A related phrasing for the same underlying problem.

connections leaked by agent code

A related phrasing for the same underlying problem.

pool checkout timeouts

A related phrasing for the same underlying problem.

Compatibility: Compatibility: pooled warehouse access (Snowflake, BigQuery slots, Postgres via PgBouncer) from agent services, current versions.

Why it happens

Pools fail gradually then suddenly: each leaked connection is invisible until the last one goes. Occupancy telemetry makes the gradual phase visible, and guaranteed release is a code-structure fix, which is why it outlasts any pool-size increase.

Edge cases / pitfalls

• Raising pool size before fixing a leak only delays the failure and increases warehouse load. Order matters.
• Warehouse concurrency and connection counts are different limits; know which one your pool presses against.
• Long analytical queries may need their own small pool so they cannot starve the agent's short operational queries.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstvGPB-JMx17Vkr2QJxMfUg