{"record":{"id":"7c4a7752a9ea8d52","repo":"eclipse-vertx/vert.x","slug":"expected-a-base64-encoded-byte-array","errorCode":null,"errorMessage":"Expected a base64 encoded byte array","messagePattern":"Expected a base64 encoded byte array","errorType":"exception","errorClass":"InvalidFormatException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/json/jackson/BufferDeserializer.java","lineNumber":33,"sourceCode":"import com.fasterxml.jackson.databind.DeserializationContext;\nimport com.fasterxml.jackson.databind.JsonDeserializer;\nimport com.fasterxml.jackson.databind.exc.InvalidFormatException;\nimport io.vertx.core.buffer.Buffer;\n\nimport java.io.IOException;\nimport java.time.Instant;\n\nimport static io.vertx.core.json.impl.JsonUtil.BASE64_DECODER;\n\nclass BufferDeserializer extends JsonDeserializer<Buffer> {\n\n  @Override\n  public Buffer deserialize(JsonParser p, DeserializationContext ctxt) throws IOException, JsonProcessingException {\n    String text = p.getText();\n    try {\n      return Buffer.buffer(BASE64_DECODER.decode(text));\n    } catch (IllegalArgumentException e) {\n      throw new InvalidFormatException(p, \"Expected a base64 encoded byte array\", text, Instant.class);\n    }\n  }\n}\n","sourceCodeStart":15,"sourceCodeEnd":37,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/json/jackson/BufferDeserializer.java#L15-L37","documentation":"BufferDeserializer decodes a JSON string into a Vert.x Buffer by base64-decoding it. When the string is not valid base64 (or uses an incompatible alphabet/padding), it throws InvalidFormatException with 'Expected a base64 encoded byte array'.","triggerScenarios":"Databind deserialization (JsonObject.mapTo / DatabindCodec.from* ) mapping a JSON field to io.vertx.core.Buffer where the field value is not valid standard base64, e.g. contains whitespace, URL-safe characters (-, _), hex, or raw binary text.","commonSituations":"A producer encoded the buffer as base64url while the deserializer expects standard base64; the JSON field holds a hex string like 'deadbeef'; the field is a plain string payload that was never base64-encoded at all.","solutions":["Base64-encode the data on the producer side using the standard (RFC 4648) alphabet: Base64.getEncoder().encodeToString(bytes).","If the input is base64url, convert it: replace '-' with '+', '_' with '/', and pad with '=' to a multiple of 4.","If the field is actually hex, decode hex first then re-encode as base64.","If the field should stay text, change the target type from Buffer to String."],"exampleFix":"// before\n{\"data\": \"deadbeef\"} // InvalidFormatException\n// after\nString b64 = Base64.getEncoder().encodeToString(Hex.decodeHex(\"deadbeef\"));\n{\"data\": b64}","handlingStrategy":"validation","validationCode":"String data = json.getString(\"data\");\nif (data != null && !data.matches(\"[A-Za-z0-9+/]*={0,2}\")) throw new IllegalArgumentException(\"data is not standard base64\");","typeGuard":"static boolean isStandardBase64(String s) {\n  return s != null && s.matches(\"[A-Za-z0-9+/]+={0,2}\") && s.length() % 4 == 0;\n}","tryCatchPattern":"try {\n  Config cfg = Json.decodeValue(body, Config.class);\n} catch (DecodeException e) {\n  if (e.getCause() instanceof InvalidFormatException ife && \"Expected a base64 encoded byte array\".equals(ife.getOriginalMessage())) {\n    // handle bad base64 field\n  }\n}","preventionTips":["Standardize on RFC 4648 standard base64 across producer and consumer.","Reject base64url/hex at the producer boundary, not the deserializer.","Document binary fields in the schema as base64-encoded."],"tags":["json","base64","deserialization","buffer"],"backgroundTag":"invalid-argument-format","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}