{"id":"ad4e9846f3cb4c01","repo":"apache/kafka","slug":"about-unable-to-retrieve-base64-encoded-binary","errorCode":null,"errorMessage":"${about}: unable to retrieve Base64-encoded binary data","messagePattern":"(.+?): unable to retrieve Base64-encoded binary data","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java","lineNumber":174,"sourceCode":"            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)\n            return null;\n        return Arrays.copyOf(array, array.length);\n    }\n\n    /**","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java#L156-L192","documentation":"Thrown by MessageUtil.jsonNodeToBinary when node.binaryValue() throws IOException — i.e. the node IS a textual Base64 string but the content is malformed (illegal characters, wrong padding, or length not a multiple of 4). The original IOException is wrapped in an UncheckedIOException carrying this message.","triggerScenarios":"A JSON string value for a `bytes` field is recognized as Base64 by Jackson but fails strict Base64 decoding: characters outside the Base64 alphabet, missing '=' padding, truncated segments, or embedded whitespace/newlines that the strict decoder rejects.","commonSituations":"Hand-editing a Base64 string and dropping a character; copy-paste that stripped trailing '=' padding; base64 output that includes URL-safe characters ('-'/'_') where standard ('+'/'/') is expected; line-wrapped PEM-style Base64 pasted as a single JSON string with newlines; encoding that used a different alphabet (RFC 4648 §5 vs §4).","solutions":["Re-encode the original bytes with standard Base64 (java.util.Base64.getEncoder() / `base64 -w0` on Linux to suppress wrapping).","Verify length is a multiple of 4 and padding ('=') is present where required.","Strip any embedded whitespace/newlines before embedding in JSON.","If you produced the value with Base64.getUrlEncoder(), switch to Base64.getEncoder() (or vice versa) to match Jackson's default RFC 4648 §4 decoder."],"exampleFix":"// before\n{\"payload\": \"aGVsbG8=d29ybGQ\"}   // missing padding, illegal mid-stream '='\n// after\n{\"payload\": \"aGVsbG8=d29ybGQ=\"}  // properly padded standard Base64","handlingStrategy":"try-catch","validationCode":"if (node != null && node.isTextual()) {\n    try { java.util.Base64.getDecoder().decode(node.asText()); }\n    catch (IllegalArgumentException ex) { throw new IllegalArgumentException(\"invalid Base64\", ex); }\n} else { throw new IllegalArgumentException(\"binary field missing\"); }","typeGuard":"node != null && node.isTextual() && java.util.Base64.getDecoder().decode(node.asText()) != null","tryCatchPattern":"try { byte[] b = MessageUtil.jsonNodeToBinary(node, about); }\ncatch (java.io.UncheckedIOException e) { /* malformed/undecodable Base64 payload; drop or DLQ */ }","preventionTips":["Pre-decode-test Base64 strings at ingest to catch truncation/padding errors early.","Validate Base64 length is a multiple of 4 (with padding).","Catch UncheckedIOException distinctly from IllegalArgumentException so IO failures are visible in logs."],"tags":["kafka","protocol","json","serialization","base64","binary","parse-error"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}