ClickHouse DB::Exception: Invalid session timeout

The INVALID_SESSION_TIMEOUT error occurs when a client requests a session timeout value that falls outside the allowed range. ClickHouse enforces both a minimum (greater than zero) and a maximum session timeout, and any value that violates these bounds is rejected with this error. You will typically see this when passing a session_timeout parameter via the HTTP interface.

Impact

The query that triggered the error fails, and no session is created or refreshed. This is a client-side configuration issue and does not affect other sessions or queries on the server. However, if the invalid timeout is hardcoded in application configuration, every attempt to establish a session will fail until the value is corrected.

Common Causes

Timeout exceeds max_session_timeout -- The requested session_timeout is larger than the server's max_session_timeout setting, which defaults to 3600 seconds (1 hour).
Timeout set to zero or a negative value -- A session timeout must be a positive integer. Passing zero or a negative number triggers this error.
Non-numeric or malformed timeout value -- Passing a string or floating-point number where an integer is expected.
Misconfigured environment variable or config template -- A template engine or environment variable substitution produces an invalid value for the timeout parameter.

Troubleshooting and Resolution Steps

Check the max_session_timeout server setting:
```
SELECT name, value FROM system.settings WHERE name = 'max_session_timeout';
```
The default is typically 3600 seconds. Your requested timeout must not exceed this value.

Set a valid session timeout in your HTTP request:

# Valid: 300 seconds (5 minutes)
curl "http://localhost:8123/?session_id=my_session&session_timeout=300" \
  --data-binary "SELECT 1"

Increase max_session_timeout on the server if needed: If your workflow genuinely requires longer sessions, adjust the server configuration in config.xml or a config fragment:
```
<clickhouse>
    <max_session_timeout>7200</max_session_timeout>
</clickhouse>
```
Then restart ClickHouse for the change to take effect.

Validate timeout values in application code: Add validation before sending requests to ClickHouse:

MAX_TIMEOUT = 3600  # Match your server's max_session_timeout

def get_session_timeout(requested):
    if requested <= 0 or requested > MAX_TIMEOUT:
        raise ValueError(f"Session timeout must be between 1 and {MAX_TIMEOUT}")
    return requested

Check for template or variable substitution issues: If your timeout value comes from an environment variable or configuration template, verify the rendered output is a valid positive integer.

Best Practices

Use session timeouts that match your actual workflow duration -- do not set excessively long timeouts as they consume server resources.
Document the max_session_timeout value for your deployment so developers know the upper bound.
Default to a moderate timeout (e.g., 60-300 seconds) and only increase it when you have a specific need.
Validate all user-supplied or dynamically generated timeout values before passing them to ClickHouse.

Frequently Asked Questions

Q: What is the default session timeout if I do not specify one?
A: The default session timeout is 60 seconds. If no session_timeout parameter is provided, ClickHouse uses this default.

Q: Can I set a session timeout of several hours?
A: Only if the server's max_session_timeout is configured to allow it. By default, the maximum is 3600 seconds (1 hour). You can increase this in the server configuration, but keep in mind that long-lived sessions consume memory.

Q: Does the session timeout reset with each query?
A: Yes. Each request that references a session ID resets the inactivity timer. The session only expires if no requests are received within the timeout window.

Q: Is this error specific to the HTTP interface?
A: Primarily, yes. The native TCP protocol handles session lifecycle differently, and you are unlikely to encounter this error when using clickhouse-client or native protocol drivers.