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

Not enough bytes to read an UTF8 serialized string preceded…

Error message

Not enough bytes to read an UTF8 serialized string preceded by its 2 bytes length

What it means

CBUtil.readString(ByteBuf) reads a 2-byte unsigned short length then that many UTF-8 bytes. If the buffer has fewer bytes than the declared length (IndexOutOfBoundsException), it throws ProtocolException stating the short-string framing was incomplete. This guards against truncated or malformed protocol frames.

Solutions

1. Check network path for truncation (proxies, packet size limits) and retransmit
2. Confirm client and server use the same native protocol version
3. Reconnect the client session to resynchronize the stream
4. Capture frames and validate the 2-byte length against the actual payload

try { ... } catch (ProtocolException e) { if (e.getMessage().contains("Not enough bytes to read an UTF8 serialized string preceded by its 2 bytes length")) { reconnectSession(); } else throw e; }

When it happens

Trigger: A short string field in a CQL protocol message declares a length exceeding the remaining readable bytes — truncated frame, wrong protocol version parsing, or a corrupt message.

Common situations: Proxy or load balancer truncating frames; a client writing a wrong length prefix; parsing frames from a different protocol version than they were encoded with.

Related errors

• Not enough bytes to read a byte array preceded by its 2…
• 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/e72364d61385bb59. Report an issue: GitHub.

Appendix: source

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

            cb.readerIndex(cb.readerIndex() + length);
            return str;
        }
        catch (IllegalStateException | CharacterCodingException e)
        {
            throw new ProtocolException("Cannot decode string as UTF8: '" + ByteBufferUtil.bytesToHex(buffer) + "'; " + e);
        }
    }

    public static String readString(ByteBuf cb)
    {
        try
        {
            int length = cb.readUnsignedShort();
            return readString(cb, length);
        }
        catch (IndexOutOfBoundsException e)
        {
            throw new ProtocolException("Not enough bytes to read an UTF8 serialized string preceded by its 2 bytes length");
        }
    }

    /**
     * Write US-ASCII strings. It does not work if containing any char > 0x007F (127)
     * @param str satisfies {@link org.apache.cassandra.db.marshal.AsciiType}
     *             i.e. seven-bit ASCII, a.k.a. ISO646-US
     */
    public static void writeAsciiString(String str, ByteBuf cb)
    {
        cb.writeShort(str.length());
        ByteBufUtil.writeAscii(cb, str);
    }

    public static void writeString(String str, ByteBuf cb)
    {
        int length = encodedUTF8Length(str);
        Preconditions.checkArgument(length <= Short.MAX_VALUE,

View on GitHub (pinned to 88fd0f6a0e)