{"id":"89fff39f53a9bc75","repo":"apache/kafka","slug":"string-length-byteslength-is-larger-than-the-ma","errorCode":null,"errorMessage":"String length ${bytesLength} is larger than the maximum string length.","messagePattern":"String length (.+?) is larger than the maximum string length\\.","errorType":"exception","errorClass":"SchemaException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/protocol/types/Type.java","lineNumber":487,"sourceCode":"            if (item instanceof Double)\n                return (Double) item;\n            else\n                throw new SchemaException(item + \" is not a Double.\");\n        }\n\n        @Override\n        public String documentation() {\n            return \"Represents a double-precision 64-bit format IEEE 754 value. \" +\n                    \"The values are encoded using eight bytes in network byte order (big-endian).\";\n        }\n    };\n\n    public static final DocumentedType STRING = new DocumentedType() {\n        @Override\n        public void write(ByteBuffer buffer, Object o) {\n            byte[] bytes = Utils.utf8((String) o);\n            if (bytes.length > Short.MAX_VALUE)\n                throw new SchemaException(\"String length \" + bytes.length + \" is larger than the maximum string length.\");\n            buffer.putShort((short) bytes.length);\n            buffer.put(bytes);\n        }\n\n        @Override\n        public String read(ByteBuffer buffer) {\n            short length = buffer.getShort();\n            if (length < 0)\n                throw new SchemaException(\"String length \" + length + \" cannot be negative\");\n            return stringRead(buffer, length);\n        }\n\n        @Override\n        public int sizeOf(Object o) {\n            return 2 + Utils.utf8Length((String) o);\n        }\n\n        @Override","sourceCodeStart":469,"sourceCodeEnd":505,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/protocol/types/Type.java#L469-L505","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before: writing an unbounded string into a STRING field\nbyte[] bytes = Utils.utf8(value);\nif (bytes.length > Short.MAX_VALUE)\n    throw new SchemaException(...); // current behavior\n\n// after: bound and truncate at the application layer\nString safe = value;\nif (Utils.utf8Length(safe) > Short.MAX_VALUE) {\n    safe = Utils.utf8(value).toString().substring(0, Short.MAX_VALUE);\n}\nschema.write(buffer, Collections.singletonMap(\"field\", safe));","handlingStrategy":"validation","validationCode":"// STRING.write rejects strings whose UTF-8 byte encoding exceeds Short.MAX_VALUE.\n// You control the input, so check the encoded length first.\nbyte[] utf8 = org.apache.kafka.common.utils.Utils.utf8(value);\nif (utf8.length > Short.MAX_VALUE) {\n    throw new IllegalArgumentException(\n        \"String UTF-8 length \" + utf8.length + \" exceeds max \" + Short.MAX_VALUE);\n}\norg.apache.kafka.common.protocol.types.Type.STRING.write(buffer, value);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["protocol","serialization","schema","string","size-limit"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}