apache/cassandra · error · RuntimeException

Unexpected error

Error message

Unexpected error

What it means

The modern-pipeline CQLMessageHandler's ErrorHandler unconditionally rethrows any dispatch/processing error as RuntimeException("Unexpected error", cause). It is a fail-fast guard: the simple test client has no strategy for frame-level processing errors, so any handler failure surfaces as this exception.

Solutions

1. Inspect the wrapped cause (RuntimeException.getCause()) to find the real handler failure.
2. Avoid protocol v5 features with SimpleClient, or downgrade the negotiated version.
3. Report the underlying deserialization/handler bug if it stems from a server frame; SimpleClient is a test client, prefer the java driver for real workloads.
4. Patch SimpleClient's errorHandler to log and close the channel rather than rethrow if you need resilience.

Example fix

// before
CQLMessageHandler.ErrorHandler errorHandler = (error) -> {
    throw new RuntimeException("Unexpected error", error);
};
// after
CQLMessageHandler.ErrorHandler errorHandler = (error) -> {
    logger.error("Handler error, closing channel", error);
    ctx.close();
};

try { v5Operation(); } catch (RuntimeException e) { if (e.getCause() != null) handleHandlerError(e.getCause()); }

When it happens

Trigger: Any exception inside the modern (v5+) message handler path — e.g. failure processing an inbound envelope, deserialization error, or resource-limit queue failure on a v5 connection.

Common situations: Exercising protocol v5 with the simple test client (which is intended for tests, not production); unexpected server frames or deserialization bugs in test tooling.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Connection Error
• Unexpected request expecting READY, AUTHENTICATE, ERROR or…
• Attempted to encode a response with an unset stream id:
• channel's transferring state is currently set to true…
• epoll not available

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

Appendix: source

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

            FrameDecoder frameDecoder = frameDecoder(ctx, allocator);
            FrameEncoder frameEncoder = frameEncoder(ctx);
            FrameEncoder.PayloadAllocator payloadAllocator = frameEncoder.allocator();

            CQLMessageHandler.MessageConsumer<Message.Response> responseConsumer = new CQLMessageHandler.MessageConsumer<Message.Response>()
            {
                public <P> void dispatch(Channel channel, Message.Response message, Dispatcher.FlushItemConverter<P> toFlushItem, P param, Overload backpressure)
                {
                    responseHandler.handleResponse(channel, message);
                }

                public boolean hasQueueCapacity()
                {
                    return true;
                }
            };

            CQLMessageHandler.ErrorHandler errorHandler = (error) -> {
                throw new RuntimeException("Unexpected error", error);
            };

            ClientResourceLimits.ResourceProvider resources = new ClientResourceLimits.ResourceProvider()
            {
                final ResourceLimits.Limit endpointReserve = new ResourceLimits.Basic(1024 * 1024 * 64);
                final AbstractMessageHandler.WaitQueue endpointQueue = AbstractMessageHandler.WaitQueue.endpoint(endpointReserve);

                final ResourceLimits.Limit globalReserve = new ResourceLimits.Basic(1024 * 1024 * 64);
                final AbstractMessageHandler.WaitQueue globalQueue = AbstractMessageHandler.WaitQueue.global(endpointReserve);

                public ResourceLimits.Limit globalLimit()
                {
                    return globalReserve;
                }

                public AbstractMessageHandler.WaitQueue globalWaitQueue()
                {
                    return globalQueue;

View on GitHub (pinned to 88fd0f6a0e)