Atlas error: timed out waiting for a connection from the pool

Not specified by the original author.

TL;DR: WaitQueueTimeoutError means every pooled connection is busy and none freed up in time. The fix is usually fewer clients or faster queries, not a bigger pool. Check for slow operations holding connections: the Real-Time Performance Panel or currentOp shows long-running ops hogging the pool. Check the Atlas Connections metric: flat at the cap means genuine exhaustion; climbing without bound means a leak.

The error

WaitQueueTimeoutError: Timed out while checking out a connection from connection pool

The fix

1. Count your clients: app instances x clients per instance. The classic bug is a new client per request or per serverless invocation, which multiplies pools without bound.
2. Check for slow operations holding connections: the Real-Time Performance Panel or currentOp shows long-running ops hogging the pool.
3. Check the Atlas Connections metric: flat at the cap means genuine exhaustion; climbing without bound means a leak.
4. Share one client per process. This fixes most cases outright.
5. Fix the slow queries first. Raising maxPoolSize on top of slow queries just moves the queue.
6. Only then raise maxPoolSize to match measured concurrent demand, or raise waitQueueTimeoutMS if bursts are brief.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas error.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

Also seen as

• waitQueueTimeoutMS

Connection pool behavior and wait-queue timeout semantics per https://www.mongodb.com/docs/manual/reference/connection-string/; monitoring via Atlas metrics per the troubleshooting guide at https://www.mongodb.com/docs/atlas/troubleshoot-connection/, verified 2026-09-26.