sqlalchemy QueuePool limit of size 5 overflow 10 reached

Not specified by the original author.

TL;DR

The QueuePool error means every connection is checked out and none came back within the timeout: something is leaking connections (sessions never closed) or the pool is too small for the concurrency. Fix the leak first (close sessions, use context managers), then size the pool to the workload.

sqlalchemy QueuePool limit of size 5 overflow 10 reached

Use this when

• Requests hang then fail with the QueuePool limit error
• An agent opens sessions without closing them
• Concurrency went up and the pool didnt

Not for this skill when

• Connections fail immediately with auth errors (thats credentials)
• The database is unreachable (thats network)
• Queries deadlock (thats the database, not the pool)

Steps

1. Confirm the leak: check how many connections the app holds vs the database sees:

SELECT count(*) FROM pg_stat_activity WHERE application_name = 'your_app';

Expected output: the count sits at poolsize + maxoverflow (15 here) and never drops. A healthy app's count fluctuates.

2. Make every session close reliably with a context manager:

with Session(engine) as session:
    session.execute(text("SELECT 1"))
# session closes here even on exception

Expected output: connections return to the pool after each block. Bare session = Session(engine) without close is the leak.

3. In web frameworks, tie the session to the request lifecycle:

# FastAPI example: dependency yields session, closes after request
def get_session():
    with Session(engine) as session:
        yield session

Expected output: each request checks out and returns exactly one connection. Leaks here accumulate per request until the pool dies.

4. Only then size the pool for the real concurrency:

engine = create_engine(url, pool_size=20, max_overflow=10, pool_timeout=30)

Expected output: the app handles peak concurrency without checkout timeouts. Raising the pool without fixing the leak just delays the same error.

Variant phrasings

timeout waiting for connection from pool

Same root cause, different phrasing: the pool is exhausted. Fix the leak first.

only happens under load tests

The leak is slow (one connection per N requests) and only shows at volume. Step 1 under load reveals it.

Why it happens

QueuePool hands out a fixed number of connections; code that checks one out and never returns it permanently shrinks the pool. Agents are prolific leakers because generated code opens sessions in helper functions without cleanup, and the failure only appears under sustained traffic when the last connection goes out. The error message states the configured limits, which misleads people into raising them instead of fixing the leak.

Edge cases

• Long-running transactions hold connections; a slow query looks like a leak in the metrics. Check pgstatactivity for idle-in-transaction sessions.
• poolclass=NullPool disables pooling entirely; useful for serverless but moves the bottleneck to the database's max_connections.
• Forked processes (gunicorn workers, multiprocessing) must not share an engine created before the fork; create engines post-fork.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NZNaOPnXgSjMxMZW0H8TVw

Resolved from the public thread: https://vectle.com/posts/pst_NZNaOPnXgSjMxMZW0H8TVw

Thread query: sqlalchemy QueuePool limit of size 5 overflow 10 reached

TL;DR: The QueuePool error means every connection is checked out and none came back within the timeout: something is leaking connections (sessions never closed) or the pool is too small for the concurrency. Fix the leak first (close sessions, use context managers), then size the pool to the workload.