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.

Not specified by the original author.

TL;DR

The scheduler opens more concurrent database connections than the pool allows, so threads block waiting for a connection and scheduling stalls. Raise sqlalchemypoolsize to cover the scheduler's parallelism, keep poolrecycle below the database idle timeout, and make sure the database itself allows that many connections. The pool, the scheduler, and the database must agree on the numbers.

airflow sqlalchemy pool exhausted, scheduler stuck

Use this when

• The scheduler stalls with pool timeout or exhausted errors.
• It happens under high DAG and task counts.
• The database shows far fewer connections than the scheduler wants.

Not for this skill when

• Queries are slow but the pool has free connections. Tune the queries.
• Workers exhaust their pools. Size worker pools separately.

Steps

1. Read the scheduler logs for pool exhaustion messages and note the configured pool size. Note the current limit. Verify: the limit is known
2. Estimate the scheduler's concurrent connection need from parallelism settings and DAG count. Note the demand. Verify: demand is quantified
3. Raise sqlalchemypoolsize to cover demand with headroom, and set maxoverflow sensibly. Note the new sizes. Verify: the pool fits the scheduler
4. Confirm the database max_connections accommodates the pool plus workers plus headroom. Note the database ceiling. Verify: the database agrees
5. Restart the scheduler and watch scheduling resume without pool errors. Note the stall is gone. Verify: the fix is verified

Variant phrasings

airflow sqlalchemypool_size tuning

The config-shaped search.

airflow scheduler database connections

The capacity phrasing.

Compatibility: Airflow 2.x. Pool settings live under [database] in airflow.cfg; scheduler parallelism under [scheduler].

Why it happens

The scheduler is surprisingly database-hungry: every scheduling loop, heartbeat, and task-state query needs a connection, and with many DAGs those add up. The default pool size was chosen for small deployments, so growing Airflow hits the ceiling as a stall rather than an error: threads wait for connections that never free up because every thread is waiting. It looks like the scheduler died, but it is just queuing internally. The three numbers, pool size, scheduler parallelism, database max_connections, must be sized as a set.

Edge cases / pitfalls

• Raising the pool without raising database max_connections moves the refusal to the database. Size all three together.
• pool_recycle must stay below the database idle timeout or you trade exhaustion for stale connections.
• Long-running queries hold pool connections hostage. A pool sized for fast queries starves on slow ones; fix the queries too.
• Multiple schedulers in HA multiply pool demand. Count every scheduler's pool against the database ceiling.

Provenance

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

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

Thread query: airflow sqlalchemy pool exhausted, scheduler stuck

TL;DR: The scheduler opens more concurrent database connections than the pool allows, so threads block waiting for a connection and scheduling stalls. Raise sqlalchemypoolsize to cover the scheduler's parallelism, keep poolrecycle below the database idle timeout, and make sure the database itself allows that many connections. The pool, the scheduler, and the database must agree on the numbers.

Not specified by the original author.

TL;DR

Upgrade to a release carrying the fix. If a Dagster webserver logs QueuePool exhaustion with sessions idle on pgclass queries, this is the bug, fixed on master (PR #34154): hastable now acquires its connection through a context manager so it returns to the pool deterministically.

Steps

1. If a Dagster webserver logs QueuePool exhaustion with sessions idle on pgclass queries, this is the bug, fixed on master (PR #34154): hastable now acquires its connection through a context manager so it returns to the pool deterministically. Upgrade to a release carrying the fix. When diagnosing any QueuePool timeout, sample pgstatactivity filtered to the webserver and look at the last SQL of idle sessions: a pile of idle sessions on the same query points at a connection-lifecycle bug in that code path, not at pool sizing.

When to use

You are seeing this: When diagnosing any QueuePool timeout, sample pgstatactivity filtered to the webserver and look at the last SQL of idle sessions: a pile of idle sessions on the same query points at a connection-lifecycle bug in that code path, not at pool sizing. Use this skill when you run into "Dagster webserver QueuePool exhaustion from unclosed has_table connection".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: GitHub issue dagster-io/dagster#34020 (closed, 7 comments): the Dagster webserver's Postgres event-log QueuePool exhausted under concurrent asset and check queries, logging QueuePool limit of size 1 overflow 50 reached. pgstatactivity showed 51 idle sessions all stuck on SQLAlchemy's table-existence query against pgcatalog.pgclass. Root cause: PostgresEventLogStorage.hastable() created a SQLAlchemy Connection without closing it, so connections stayed checked out until cyclic garbage collection ran, which is nondeterministic. Raising maxoverflow or pool recycling would only have delayed the exhaustion.

Verified resolution: If a Dagster webserver logs QueuePool exhaustion with sessions idle on pgclass queries, this is the bug, fixed on master (PR #34154): hastable now acquires its connection through a context manager so it returns to the pool deterministically. Upgrade to a release carrying the fix. When diagnosing any QueuePool timeout, sample pgstatactivity filtered to the webserver and look at the last SQL of idle sessions: a pile of idle sessions on the same query points at a connection-lifecycle bug in that code path, not at pool sizing.

Source URL: https://github.com/dagster-io/dagster/issues/34020