apache/kafka · error · SchemaException

String length ${bytesLength} is larger than the maximum stri

Error message

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

What it means

Thrown by STRING.write() when serializing a String whose UTF-8 byte count exceeds Short.MAX_VALUE (32767). The legacy STRING type writes a signed INT16 length prefix, so any payload longer than 32 KB is physically unrepresentable. This is a producer-side guard preventing the write of an invalid frame.

Source

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

            if (item instanceof Double)
                return (Double) item;
            else
                throw new SchemaException(item + " is not a Double.");
        }

        @Override
        public String documentation() {
            return "Represents a double-precision 64-bit format IEEE 754 value. " +
                    "The values are encoded using eight bytes in network byte order (big-endian).";
        }
    };

    public static final DocumentedType STRING = new DocumentedType() {
        @Override
        public void write(ByteBuffer buffer, Object o) {
            byte[] bytes = Utils.utf8((String) o);
            if (bytes.length > Short.MAX_VALUE)
                throw new SchemaException("String length " + bytes.length + " is larger than the maximum string length.");
            buffer.putShort((short) bytes.length);
            buffer.put(bytes);
        }

        @Override
        public String read(ByteBuffer buffer) {
            short length = buffer.getShort();
            if (length < 0)
                throw new SchemaException("String length " + length + " cannot be negative");
            return stringRead(buffer, length);
        }

        @Override
        public int sizeOf(Object o) {
            return 2 + Utils.utf8Length((String) o);
        }

        @Override

View on GitHub (pinned to c31c9215e1)

Solutions

Reduce the string payload to under 32 KB of UTF-8 before writing; truncate or hash long values.
Move the payload to a field encoded with COMPACT_STRING or NULLABLE_STRING only if the receiving API version supports it (otherwise the encoding is fixed by the schema).
Validate length at the application boundary (before handing the value to the Kafka client) and fail with a domain-specific error.
If you control both ends, bump the API version that uses a varint/nullable string encoding for that field.

Example fix

// before: writing an unbounded string into a STRING field
byte[] bytes = Utils.utf8(value);
if (bytes.length > Short.MAX_VALUE)
    throw new SchemaException(...); // current behavior

// after: bound and truncate at the application layer
String safe = value;
if (Utils.utf8Length(safe) > Short.MAX_VALUE) {
    safe = Utils.utf8(value).toString().substring(0, Short.MAX_VALUE);
}
schema.write(buffer, Collections.singletonMap("field", safe));

Defensive patterns

Strategy: validation

Validate before calling

// STRING.write rejects strings whose UTF-8 byte encoding exceeds Short.MAX_VALUE.
// You control the input, so check the encoded length first.
byte[] utf8 = org.apache.kafka.common.utils.Utils.utf8(value);
if (utf8.length > Short.MAX_VALUE) {
    throw new IllegalArgumentException(
        "String UTF-8 length " + utf8.length + " exceeds max " + Short.MAX_VALUE);
}
org.apache.kafka.common.protocol.types.Type.STRING.write(buffer, value);

Prevention

The limit is on UTF-8 *byte* length, not character count — a 32767-char ASCII string fits but a multi-byte string may not; always measure bytes, not chars.
Enforce a topic/config-name length cap in your application logic (well under 32767 bytes) so oversized values never reach the serializer.
Switch to NULLABLE_STRING/COMPACT_STRING only if you need null or compact encoding — the 32767-byte cap is identical across all of them.

When it happens

Trigger: Calling STRING.write(buffer, o) with a String whose Utils.utf8(...).length > 32767. Reached via Schema.write / SendBuilder when building a request or response that contains a legacy STRING field (common in older API versions and in some config/credential fields).

Common situations: Passing an oversized client.id, principal name, SASL mechanism token, or config value into a legacy API that uses STRING. Concatenating dynamic content (e.g. a JSON blob) into a field that was meant to hold a short identifier. Migrating data from a system without length limits.

Related errors

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