apache/cassandra · error · RuntimeException

timeout

Error message

timeout

What it means

SimpleClient.execute() writes a request frame and then waits up to TIMEOUT_SECONDS on the response queue; if no response arrives in that window it throws a plain RuntimeException("timeout"). This is a synchronous client-side wait timeout, not necessarily a server-side query timeout — the response may have been lost, the server busy, or the write itself stalled.

Solutions

1. Check server health/logs for slow queries or GC pauses during the window.
2. Retry the request; SimpleClient has no built-in retry or speculative execution.
3. Increase TIMEOUT_SECONDS in SimpleClient if latency is legitimately high, or use the java driver which has configurable, per-request timeouts.
4. Verify the channel is still open (channel.isActive()) before writing; reconnect on failure.

Example fix

// before
Message.Response resp = client.execute("SELECT * FROM t", ConsistencyLevel.ONE);
// after
try {
    Message.Response resp = client.execute("SELECT * FROM t", ConsistencyLevel.ONE);
} catch (RuntimeException e) {
    if ("timeout".equals(e.getMessage())) { client.close(); client.connect(false); /* retry */ }
}

// pre-flight
if (!client.connection.channel().isActive()) { client.close(); client.connect(false); }

try { return client.execute(query, cl); } catch (RuntimeException e) { if ("timeout".equals(e.getMessage())) { reconnect(); return retry(query, cl); } throw e; }

When it happens

Trigger: Calling execute()/execute(query, values, consistency) and Message.Response poll(TIMEOUT_SECONDS) returns null because the server did not answer within the fixed timeout.

Common situations: Heavy server load or long-running queries exceeding the client timeout; a dropped connection after the write (lastWriteFuture never completed); server GC pauses; using the simple test client against a production cluster under load.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Connection Error
• Could not discover CMS from
• Could not fetch log entries from peer, remote =
• No response from
• Unexpected REQUEST message

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/3be336dd7b34888b. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/SimpleClient.java:333

        // Shut down all thread pools to exit.
        bootstrap.group().shutdownGracefully();
    }

    public Message.Response execute(Message.Request request)
    {
        return execute(request, true);
    }

    public Message.Response execute(Message.Request request, boolean throwOnErrorResponse)
    {
        try
        {
            request.attach(connection);
            lastWriteFuture = channel.writeAndFlush(Collections.singletonList(request));
            Message.Response msg = responseHandler.responses.poll(TIMEOUT_SECONDS, TimeUnit.SECONDS);
            if (msg == null)
                throw new RuntimeException("timeout");
            if (throwOnErrorResponse && msg instanceof ErrorMessage)
                throw new RuntimeException((Throwable)((ErrorMessage)msg).error);
            return msg;
        }
        catch (InterruptedException e)
        {
            throw new UncheckedInterruptedException(e);
        }
    }

    public Map<Message.Request, Message.Response> execute(List<Message.Request> requests)
    {
        try
        {
            Map<Message.Request, Message.Response> rrMap = new HashMap<>();

            if (version.isGreaterOrEqualTo(ProtocolVersion.V5))
            {

View on GitHub (pinned to 88fd0f6a0e)