sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached, connection timed out, timeout 30.00
ID: database/connection-pool-exhausted
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 16 | active | — | — | — |
Root Cause
The application-level connection pool has no available connections. All pool connections are checked out and in use (or leaked). This is different from PostgreSQL's max_connections limit; it is the application pool's own limit. Caused by connection leaks, slow queries holding connections, or undersized pool.
genericWorkarounds
-
92% success Fix connection leaks by ensuring all connections are returned to the pool
In SQLAlchemy, always use 'with engine.connect() as conn:' or scoped sessions that are properly closed. Enable pool_pre_ping=True to detect stale connections. Set pool_recycle=3600 to recycle connections periodically. Log pool checkout events to identify code paths that never return connections.
-
87% success Tune pool size and timeout parameters based on actual workload
Set pool_size to match the expected concurrent database operations (not total requests). In SQLAlchemy: create_engine(url, pool_size=20, max_overflow=10, pool_timeout=30). Monitor pool usage with pool.status(). Rule of thumb: pool_size should be slightly above the average concurrent query count.
Dead Ends
Common approaches that don't work:
-
Setting the pool size extremely high without fixing the underlying leak
80% fail
A larger pool masks the leak temporarily but eventually the pool fills up again and the error returns. Meanwhile, the large number of open connections may hit PostgreSQL's max_connections limit, creating a new error.
-
Disabling connection pooling entirely and opening new connections per request
75% fail
Opening a new PostgreSQL connection takes 100-200ms due to process forking and authentication. Without pooling, performance degrades severely under load, and you risk hitting PostgreSQL's max_connections limit directly.