apache/cassandra · error · ProtocolException

Unsupported message

Error message

Unsupported message

What it means

This codec is a placeholder for message types that have no wire representation (e.g. Options/Startup on some paths). Its decode method always throws a ProtocolException; if the protocol version is actually a supported one it first logs an error, indicating a corrupted/invalid frame routed the wrong message type rather than a legitimate unsupported version.

Solutions

1. Fix the client to send only valid opcodes for the negotiated protocol version
2. Check for proxies/load balancers corrupting the native protocol stream
3. Update the client driver to a supported release
4. Enable driver and server protocol logging to identify the offending opcode

catch (io errors / ProtocolException) on the connection; log the opcode and negotiated version, then reconnect and renegotiate

When it happens

Trigger: A frame with a message opcode mapped to UnsupportedMessageCodec arrives on a connection using a supported protocol version — i.e. a malformed or out-of-order message type (e.g. a client sending an unexpected opcode where a decoded body is expected).

Common situations: Buggy or hand-rolled client implementations sending wrong opcodes; corrupted frames from a broken intermediary/proxy; protocol implementation bugs in drivers during version negotiation.

Related errors

• Cannot parse 32-bits int value from
• Cannot parse 64-bits double value from
• Cannot parse 64-bits long value from
• Cannot parse boolean value from
• Cannot parse date value from

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

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/messages/UnsupportedMessageCodec.java:45

import io.netty.buffer.ByteBuf;

/**
 * Catch-all codec for any unsupported legacy messages.
 */
public class UnsupportedMessageCodec <T extends Message> implements Message.Codec<T>
{
    public final static UnsupportedMessageCodec instance = new UnsupportedMessageCodec();

    private static final Logger logger = LoggerFactory.getLogger(UnsupportedMessageCodec.class);

    public T decode(ByteBuf body, ProtocolVersion version)
    {
        if (ProtocolVersion.SUPPORTED.contains(version))
        {
            logger.error("Received invalid message for supported protocol version {}", version);
        }
        throw new ProtocolException("Unsupported message");
    }

    public void encode(T t, ByteBuf dest, ProtocolVersion version)
    {
        throw new ProtocolException("Unsupported message");
    }

    public int encodedSize(T t, ProtocolVersion version)
    {
        return 0;
    }
}

View on GitHub (pinned to 88fd0f6a0e)