apache/cassandra · error · org.apache.cassandra.transport.ProtocolException

Not enough bytes to read a byte array preceded by its 2…

Error message

Not enough bytes to read a byte array preceded by its 2 bytes length

What it means

CBUtil.readBytes(ByteBuf) reads a 2-byte length followed by that many raw bytes. If the buffer lacks the declared bytes (IndexOutOfBoundsException), it throws ProtocolException noting the byte-array framing is incomplete. Protects binary field parsing in the CQL native protocol.

Solutions

1. Reconnect the client to reset the stream
2. Check for intermediaries that truncate or rewrite frames
3. Verify custom client code writes the correct 2-byte length before each byte array
4. Capture and inspect frames to find where the stream desyncs

try { ... } catch (ProtocolException e) { if (e.getMessage().contains("byte array preceded by its 2 bytes length")) { reconnectSession(); } else throw e; }

When it happens

Trigger: A bytes field in a protocol message (e.g., protocol options, custom payload entries) declares a short length exceeding remaining readable bytes.

Common situations: Corrupted or truncated connection stream; misaligned parsing after an earlier bad read; buggy custom client writing wrong lengths for binary fields.

Related errors

• Not enough bytes to read an UTF8 serialized string preceded…
• Not enough bytes to read an UTF8 serialized string preceded…
• Cannot read value of length
• Invalid ByteBuf length " + length
• Beta version of server used

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

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/CBUtil.java:241

    }

    public static int sizeOfLongString(String str)
    {
        return 4 + encodedUTF8Length(str);
    }

    public static byte[] readBytes(ByteBuf cb)
    {
        try
        {
            int length = cb.readUnsignedShort();
            byte[] bytes = new byte[length];
            cb.readBytes(bytes);
            return bytes;
        }
        catch (IndexOutOfBoundsException e)
        {
            throw new ProtocolException("Not enough bytes to read a byte array preceded by its 2 bytes length");
        }
    }

    public static void writeBytes(byte[] bytes, ByteBuf cb)
    {
        cb.writeShort(bytes.length);
        cb.writeBytes(bytes);
    }

    public static int sizeOfBytes(byte[] bytes)
    {
        return 2 + bytes.length;
    }

    public static Map<String, ByteBuffer> readBytesMap(ByteBuf cb)
    {
        int length = cb.readUnsignedShort();
        Map<String, ByteBuffer> m = new HashMap<>(length);

View on GitHub (pinned to 88fd0f6a0e)