ClickHouse DB::Exception: Session refused

The SESSION_REFUSED error occurs when ClickHouse declines to create a new session. This typically happens when the server has reached its maximum number of concurrent sessions or is under conditions that prevent it from accepting new session state. The client receives a clear rejection indicating that the session could not be established.

Impact

Any workflow that depends on session features -- temporary tables, session-scoped settings, or multi-step operations -- will be blocked. The error does not affect existing sessions or stateless queries, so operations that do not require a session will continue to work normally. Under heavy load, multiple clients may experience this error simultaneously if the session limit is a shared resource.

Common Causes

1. Maximum session limit reached -- ClickHouse has an internal limit on the number of concurrent sessions. When this limit is hit, new session creation is refused.
2. Session leak in application code -- Applications that create sessions but never let them expire (by continuously sending keepalive queries) can exhaust the session pool over time.
3. Aggressive retry logic creating many sessions -- Retry mechanisms that create a new session on each attempt without cleaning up previous ones.
4. High concurrency with session-dependent workloads -- A spike in concurrent users or batch jobs that all require sessions can push past the limit.
5. Server resource constraints -- In extreme memory pressure situations, the server may refuse to allocate resources for new sessions.

Troubleshooting and Resolution Steps

1. Check current session usage: Look at active queries and their associated sessions to understand current utilization:

   SELECT count(), countDistinct(settings['session_id']) AS unique_sessions
   FROM system.processes
   WHERE settings['session_id'] != '';
   

2. Identify session leaks: Review your application code for patterns where sessions are created but never allowed to expire. Ensure that session timeouts are reasonable:

   # Use a short timeout so sessions auto-expire
   curl "http://localhost:8123/?session_id=temp_session&session_timeout=60" \
     --data-binary "SELECT 1"
   

3. Reduce unnecessary session usage: Audit your application to identify queries that use sessions but do not actually need them. Remove the session_id parameter from stateless queries.

4. Implement session pooling: Rather than creating a new session per request, maintain a pool of session IDs and reuse them:

   from queue import Queue
   import uuid
   
   session_pool = Queue(maxsize=50)
   for _ in range(50):
       session_pool.put(str(uuid.uuid4()))
   
   def get_session():
       return session_pool.get()
   
   def release_session(sid):
       session_pool.put(sid)
   

5. Shorten session timeouts: If sessions are accumulating because of long timeouts, reduce the timeout value so idle sessions are cleaned up faster:

   curl "http://localhost:8123/?session_id=my_session&session_timeout=30" \
     --data-binary "SELECT 1"
   

6. Scale horizontally: If legitimate workload requires more sessions than a single server can handle, distribute sessions across multiple ClickHouse nodes using a load balancer with session affinity.

Best Practices

• Set session timeouts as short as your workflow allows so idle sessions do not accumulate.
• Use sessions only when genuinely needed -- most ClickHouse queries work perfectly without them.
• Monitor active session counts as part of your ClickHouse observability stack.
• Implement a session pool in your application rather than creating sessions on demand without limits.
• Add alerting for when session counts approach the server limit.

Frequently Asked Questions

Q: What is the maximum number of concurrent sessions ClickHouse supports?
A: The default limit depends on the ClickHouse version and build. It is generally generous enough for typical workloads, but it can be exhausted by applications that create sessions aggressively. Check your server logs or source configuration for the exact limit.

Q: Will stateless queries still work when sessions are refused?
A: Yes. The SESSION_REFUSED error only affects requests that attempt to create or use a session. Regular queries without a session_id are unaffected.

Q: Can I increase the maximum session limit?
A: This is not a commonly exposed tunable in ClickHouse server configuration. The better approach is to reduce session consumption by shortening timeouts and eliminating unnecessary sessions.

Q: How do I know if my sessions are leaking?
A: If the number of active sessions grows monotonically over time and never decreases, you likely have a session leak. Monitor session-related metrics and correlate them with your application deployment cycles.