{"id":"fbd0849bc6e914c4","repo":"apache/kafka","slug":"about-expected-base64-encoded-binary-data","errorCode":null,"errorMessage":"${about}: expected Base64-encoded binary data.","messagePattern":"(.+?): expected Base64-encoded binary data\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java","lineNumber":169,"sourceCode":"            } catch (NumberFormatException e) {\n                throw new NumberFormatException(about + \": failed to \" +\n                    \"parse hexadecimal number: \" + e.getMessage());\n            }\n        } else {\n            try {\n                return Long.parseLong(text);\n            } catch (NumberFormatException e) {\n                throw new NumberFormatException(about + \": failed to \" +\n                    \"parse number: \" + e.getMessage());\n            }\n        }\n    }\n\n    public static byte[] jsonNodeToBinary(JsonNode node, String about) {\n        try {\n            byte[] value = node.binaryValue();\n            if (value == null) {\n                throw new IllegalArgumentException(about + \": expected Base64-encoded binary data.\");\n            }\n\n            return value;\n        } catch (IOException e) {\n            throw new UncheckedIOException(about + \": unable to retrieve Base64-encoded binary data\", e);\n        }\n    }\n\n    public static double jsonNodeToDouble(JsonNode node, String about) {\n        if (!node.isFloatingPointNumber()) {\n            throw new NumberFormatException(about + \": expected a floating point \" +\n                \"type, but got \" + node.getNodeType());\n        }\n        return node.asDouble();\n    }\n\n    public static byte[] duplicate(byte[] array) {\n        if (array == null)","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java#L151-L187","documentation":"Thrown by MessageUtil.jsonNodeToBinary when Jackson's node.binaryValue() returns null, meaning the node is not a JSON string containing Base64-encoded binary data. Kafka uses this reader for `bytes` protocol fields such as RawTaggedField payloads, transactional IDs, and certain opaque blobs that are serialized as Base64 text in JSON form.","triggerScenarios":"A JSON value for a `bytes` field is provided as a non-string node (number, object, array, boolean, null) or as a string that Jackson cannot interpret as Base64. node.binaryValue() returns null and line 169 throws IllegalArgumentException.","commonSituations":"Passing raw UTF-8 text where Base64 is expected (e.g. \"hello\" instead of \"aGVsbG8=\"); passing null where bytes are required; sending a JSON object/array because the field name was reused; mis-rendering a byte[] from a Java dump that printed toString() rather than Base64.","solutions":["Encode the binary payload as Base64 (e.g. Base64.getEncoder().encodeToString(bytes) in Java or `base64` on the CLI) and put that string in the JSON.","Confirm the node is a JSON string literal (quoted) — Jackson only decodes Base64 from TextNode.","Verify the field actually expects bytes (check the message spec); if it expects a string, use the string accessor instead.","If the field is optional and the value should be empty, pass an empty Base64 string \"\" rather than null."],"exampleFix":"// before\n{\"transactional_id\": \"txn-42\", \"payload\": \"raw bytes here\"}\n// after\n{\"transactional_id\": \"txn-42\", \"payload\": \"cmF3IGJ5dGVzIGhlcmU=\"}","handlingStrategy":"validation","validationCode":"if (node == null || !node.isTextual()) throw new IllegalArgumentException(\"binary field must be a Base64 string\");\nbyte[] b = java.util.Base64.getDecoder().decode(node.asText()); // throws on malformed","typeGuard":"node != null && node.isTextual() && node.asText().matches(\"^[A-Za-z0-9+/]*={0,2}$\")","tryCatchPattern":"try { byte[] b = MessageUtil.jsonNodeToBinary(node, about); }\ncatch (IllegalArgumentException e) { /* not Base64 text; reject record */ }","preventionTips":["Always Base64-encode bytes (standard alphabet, with padding) before placing them in JSON.","Do not put raw byte arrays, hex strings, or arrays of ints into binary fields.","Use the same Base64 variant (standard vs URL-safe) on producer and consumer."],"tags":["kafka","protocol","json","serialization","base64","binary"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}