apache/kafka · error · SchemaException

String length ${length} is larger than the maximum string le

Error message

String length ${length} is larger than the maximum string length.

What it means

Thrown by stringRead() when decoding a Kafka protocol STRING field whose declared length exceeds Short.MAX_VALUE (32767). The legacy STRING type encodes length as a signed INT16, so any value outside [-32768, 32767] is physically impossible to represent; this guard rejects malformed or truncated frames before allocating a giant buffer. It is a hard schema-validation failure raised as a SchemaException.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/protocol/types/Type.java:122

         */
        public abstract String typeName();

        /**
         * Documentation of the Type.
         *
         * @return details about valid values, representation
         */
        public abstract String documentation();

        @Override
        public String toString() {
            return typeName();
        }
    }

    public static String stringRead(ByteBuffer buffer, int length) {
        if (length > Short.MAX_VALUE)
            throw new SchemaException("String length " + length + " is larger than the maximum string length.");
        if (length > buffer.remaining())
            throw new SchemaException("Error reading string of length " + length + ", only " + buffer.remaining() + " bytes available");
        String result = Utils.utf8(buffer, length);
        buffer.position(buffer.position() + length);
        return result;
    }

    public static ByteBuffer bytesRead(ByteBuffer buffer, int size) {
        if (size > buffer.remaining())
            throw new SchemaException("Error reading bytes of size " + size + ", only " + buffer.remaining() + " bytes available");

        int limit = buffer.limit();
        int newPosition = buffer.position() + size;
        buffer.limit(newPosition);
        ByteBuffer val = buffer.slice();
        buffer.limit(limit);
        buffer.position(newPosition);
        return val;

View on GitHub (pinned to c31c9215e1)

Solutions

Verify the byte buffer being decoded actually came from a Kafka protocol response/request at the expected API key and version.
Check that buffer.position()/limit() are correctly set before the read; dump the surrounding bytes to confirm the length prefix is sane.
Confirm client and broker versions are compatible for the API key in the failing exchange (enable DEBUG org.apache.kafka.common.protocol for the API key).
If the payload originates from your own serialization, re-encode it with the matching Schema rather than hand-built buffers.

Example fix

// before: handing a raw truncated buffer to STRING.read
short len = buffer.getShort();
String v = Type.stringRead(buffer, len); // throws if len > 32767

// after: guard the length and surface a clearer error
short len = buffer.getShort();
if (len < 0 || len > Short.MAX_VALUE || len > buffer.remaining())
    throw new SchemaException("Malformed STRING field: length=" + len
        + " remaining=" + buffer.remaining());
String v = Utils.utf8(buffer, len);

Defensive patterns

Strategy: validation

Validate before calling

// stringRead(buffer, length) is public and takes length as a param.
// Reject oversized lengths BEFORE calling it.
if (length > Short.MAX_VALUE) {
    throw new IllegalArgumentException(
        "String length " + length + " exceeds max " + Short.MAX_VALUE);
}
String value = org.apache.kafka.common.protocol.types.Type.stringRead(buffer, length);

Prevention

stringRead is a public static helper that takes the already-decoded length as an argument; validate that argument against Short.MAX_VALUE (32767) before the call.
Treat any length close to 32767 as suspicious — it usually signals a corrupt or hostile frame; log and drop the buffer rather than proceeding.
If you do not control the buffer (e.g. data straight off the wire), wrap the read in try/catch SchemaException instead — validation only helps when you already hold the length field.

When it happens

Trigger: Calling STRING.read(buffer) (or Schema.read on a buffer containing a STRING field) where the first two bytes decoded as a short exceed 32767; reached indirectly via ApiMessage deserialization, RequestMessage, or SendBuilder on a corrupt/length-mismatched ByteBuffer. Also hit by stringRead() invoked from COMPACT_STRING.read when the decoded varint length is oversized.

Common situations: Wire-level corruption from a partial write, network truncation, or reading a buffer whose position was not reset. Mismatched client/broker protocol versions where a newer field is interpreted as STRING length. Accidentally handing a non-Kafka payload (e.g. a TLS record or HTTP body) to a Kafka deserializer.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/fec07b7c7ff99257.json. Report an issue: GitHub.