{"id":"cbb763ef76068b58","repo":"apache/kafka","slug":"input-string-str-decoded-as-uuidbytes-remaining","errorCode":null,"errorMessage":"Input string `str` decoded as uuidBytes.remaining() bytes, which is not equal to the expected 16 bytes of a base64-encoded UUID","messagePattern":"Input string `str` decoded as uuidBytes\\.remaining\\(\\) bytes, which is not equal to the expected 16 bytes of a base64-encoded UUID","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/Uuid.java","lineNumber":142,"sourceCode":"     * Returns a base64 string encoding of the UUID.\n     */\n    @Override\n    public String toString() {\n        return Base64.getUrlEncoder().withoutPadding().encodeToString(getBytesFromUuid());\n    }\n\n    /**\n     * Creates a UUID based on a base64 string encoding used in the toString() method.\n     */\n    public static Uuid fromString(String str) {\n        if (str.length() > 24) {\n            throw new IllegalArgumentException(\"Input string with prefix `\"\n                + str.substring(0, 24) + \"` is too long to be decoded as a base64 UUID\");\n        }\n\n        ByteBuffer uuidBytes = ByteBuffer.wrap(Base64.getUrlDecoder().decode(str));\n        if (uuidBytes.remaining() != 16) {\n            throw new IllegalArgumentException(\"Input string `\" + str + \"` decoded as \"\n                + uuidBytes.remaining() + \" bytes, which is not equal to the expected 16 bytes \"\n                + \"of a base64-encoded UUID\");\n        }\n\n        return new Uuid(uuidBytes.getLong(), uuidBytes.getLong());\n    }\n\n    private byte[] getBytesFromUuid() {\n        // Extract bytes for uuid which is 128 bits (or 16 bytes) long.\n        ByteBuffer uuidBytes = ByteBuffer.wrap(new byte[16]);\n        uuidBytes.putLong(this.mostSignificantBits);\n        uuidBytes.putLong(this.leastSignificantBits);\n        return uuidBytes.array();\n    }\n\n    @Override\n    public int compareTo(Uuid other) {\n        if (mostSignificantBits > other.mostSignificantBits) {","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/Uuid.java#L124-L160","documentation":"Thrown by Uuid.fromString(String) when the supplied string, after URL-safe Base64 decoding, does not yield exactly 16 bytes (a 128-bit UUID). Kafka's Uuid.toString() produces a 22-character unpadded URL-safe Base64 string (Base64.getUrlEncoder().withoutPadding()), and fromString() is its strict inverse, so any other encoding (dashed hex, padded Base64, truncated data, raw text) is rejected. The IllegalArgumentException surfaces a corrupt or wrongly-formatted topic/partition ID string that the caller expected to round-trip into a Uuid.","triggerScenarios":"Calling Uuid.fromString(str) where str is a java.util.UUID-style dashed hex string (36 chars), a standard (non-URL-safe or padded) Base64 string, a value shorter/longer than 22 chars that doesn't decode to 16 bytes, or an arbitrary string token. Happens when deserializing a topic-id stored in a config file, JSON payload, URL path parameter, or command-line arg and passing it directly into Uuid.fromString().","commonSituations":"Persisting a Uuid via toString() but later reconstructing it from a different representation (e.g. storing the java.util.UUID.toString() form); copy/paste truncating a 22-char base64 id; migrating from older code that used UUID.fromString(); reading topic IDs from KRaft metadata tooling output or AdminClient responses and feeding them back in the wrong format.","solutions":["Only pass values that were produced by Uuid.toString() (22-char unpadded URL-safe Base64) into Uuid.fromString().","If you hold a java.util.UUID, convert with new Uuid(jUuid.getMostSignificantBits(), jUuid.getLeastSignificantBits()) instead of string parsing.","If you have a hex/dashed UUID string, parse it with java.util.UUID.fromString() first, then build the Kafka Uuid from its two longs.","Validate length and charset (URL-safe Base64 alphabet, 22 chars, no padding) before calling fromString() to give a clearer upstream error."],"exampleFix":"// before\nUuid id = Uuid.fromString(javaUuid.toString()); // dashed hex, decodes to != 16 bytes\n\n// after\njava.util.UUID j = java.util.UUID.fromString(javaUuid.toString());\nUuid id = new Uuid(j.getMostSignificantBits(), j.getLeastSignificantBits());","handlingStrategy":"validation","validationCode":"// Validate a candidate string is a round-trippable Kafka Uuid before calling Uuid.fromString(...)\nString s = /* untrusted */;\nif (s == null || s.length() > 24) { /* reject: wrong shape */ }\nbyte[] decoded;\ntry {\n    decoded = Base64.getUrlDecoder().decode(s);\n} catch (IllegalArgumentException e) { /* reject: not valid url-safe base64 */ }\nif (decoded.length != 16) { /* reject: not a UUID payload */ }\n// Only now: Uuid.fromString(s);","typeGuard":"// Narrow an arbitrary Object/String to a base64-encoded Kafka Uuid\nstatic boolean isBase64UuidString(Object o) {\n    if (!(o instanceof String)) return false;\n    String s = (String) o;\n    if (s.length() > 24) return false;\n    byte[] d;\n    try { d = Base64.getUrlDecoder().decode(s); }\n    catch (IllegalArgumentException e) { return false; }\n    return d.length == 16;\n}","tryCatchPattern":"// Only when input truly cannot be pre-validated\ntry {\n    Uuid id = Uuid.fromString(s);\n} catch (IllegalArgumentException e) {\n    // covers both the length-prefixed message and the 16-byte message;\n    // treat as malformed identifier, do not retry with the same input\n}","preventionTips":["Only feed Uuid.fromString values produced by Uuid.toString() or received from a trusted Kafka API response.","Treat Uuid strings arriving from logs, URLs, or user input as untrusted; validate length (<=24 chars) and base64 shape first.","Centralize UUID parsing in one helper that validates + catches IllegalArgumentException, so callers cannot hit the raw throw.","Remember Kafka Uuid is NOT java.util.UUID: it uses url-safe base64 without padding, not the standard 8-4-4-4-12 hex form."],"tags":["uuid","base64","serialization","argument","java"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}