spanner 'session pool exhausted' in the client library: how to size it

Not specified by the original author.

TL;DR

The client library's session pool is smaller than your concurrency. Raise the maximum sessions to cover peak concurrent operations, make sure every session is returned to the pool (use context managers or try/finally), and watch for leaked sessions in the client metrics. Sessions are the unit of concurrency in Spanner; exhaust them and new work queues until it times out.

Session pool exhausted

Steps

1. Find your pool settings: in the client constructor, note the min and max session counts. Expected: you know the current ceiling.
2. Check whether sessions leak. Every session must be closed and returned; audit for missing close calls, especially in error paths, and use try/finally or context managers. Expected: session counts in metrics return to baseline after traffic stops.
3. Raise the max sessions to cover peak concurrency plus headroom. Concurrent in-flight operations is the number that matters, not total requests. Expected: the exhaustion errors stop at the same traffic level.
4. Raise the min sessions if bursts hit a cold pool; pre-warmed sessions avoid checkout latency spikes on deploy or traffic ramps. Expected: latency stays stable during bursts.
5. Monitor the pool: export client metrics for sessions in use versus pool size, and alert before it saturates. Expected: a dashboard showing pool utilization with an alert threshold below the max.

Use this when

• The Spanner client throws session pool exhausted errors
• Errors correlate with concurrency spikes
• A service works at low traffic and fails at high traffic
• There are no database-side errors; the database itself is healthy

Not for this skill when

• Spanner reports resource exhausted on the database side (that is instance CPU or storage, not the client pool)
• You see session-not-found errors (stale sessions, a different fix)
• There is latency but no errors (that is a query or instance-sizing question)

Variant phrasings

• spanner no sessions available
• spanner client session pool size
• google cloud spanner max sessions
• spanner session leak

Why it happens

The Spanner client multiplexes database sessions from a local pool. Each concurrent read or write holds one session. The pool has a maximum, and when every session is checked out, new operations wait and then fail instead of overwhelming the database. That is the pool doing its job, just sized too small for the workload.

Edge cases

• Async clients need their own pool tuning; sync settings do not transfer.
• A session leak looks identical to an undersized pool; fix leaks before raising the max.
• Each Spanner database has server-side session limits too; the client max cannot exceed what the instance allows.
• Long-running transactions pin sessions; keep them short.

Provenance

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

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

Thread query: spanner 'session pool exhausted' in the client library: how to size it

TL;DR: The client library's session pool is smaller than your concurrency. Raise the maximum sessions to cover peak concurrent operations, make sure every session is returned to the pool (use context managers or try/finally), and watch for leaked sessions in the client metrics. Sessions are the unit of concurrency in Spanner; exhaust them and new work queues until it times out.