{"record":{"id":"eca313db746a8bb2","repo":"eclipse-vertx/vert.x","slug":"expected-a-base64-encoded-byte-array-eca313","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/ByteArrayDeserializer.java","lineNumber":32,"sourceCode":"import com.fasterxml.jackson.core.JsonProcessingException;\nimport com.fasterxml.jackson.databind.DeserializationContext;\nimport com.fasterxml.jackson.databind.JsonDeserializer;\nimport com.fasterxml.jackson.databind.exc.InvalidFormatException;\n\nimport java.io.IOException;\nimport java.time.Instant;\n\nimport static io.vertx.core.json.impl.JsonUtil.BASE64_DECODER;\n\nclass ByteArrayDeserializer extends JsonDeserializer<byte[]> {\n\n  @Override\n  public byte[] deserialize(JsonParser p, DeserializationContext ctxt) throws IOException, JsonProcessingException {\n    String text = p.getText();\n    try {\n      return 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":14,"sourceCodeEnd":36,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/json/jackson/ByteArrayDeserializer.java#L14-L36","documentation":"ByteArrayDeserializer decodes a JSON string into byte[] via base64. Invalid base64 input makes it throw InvalidFormatException 'Expected a base64 encoded byte array'. Same family as the Buffer deserializer but targeting byte[].","triggerScenarios":"JsonObject.mapTo(MyDto.class) or Json.decodeValue(...).mapTo(...) where a byte[]/Byte[] field maps to a JSON string that is not valid standard base64 (URL-safe chars, whitespace, hex, empty garbage).","commonSituations":"Cross-language producers emitting base64url (Node, Go) consumed by Vert.x expecting standard base64; hand-crafted test fixtures with pseudo-encoded strings; fields holding raw text like 'hello world!' with illegal characters.","solutions":["Encode with standard base64 on the producer: Base64.getEncoder().encodeToString(bytes).","Normalize base64url input to standard before sending (char swap + padding).","Check for accidental whitespace/newlines inside the string value.","Map to String and decode manually with a lenient decoder if non-standard encodings must be accepted."],"exampleFix":"// before\n{\"payload\": \"a-b_c\"} // base64url -> InvalidFormatException\n// after\nString std = Base64.getUrlDecoder().decode(urlB64) then re-encode;\n{\"payload\": Base64.getEncoder().encodeToString(bytes)}","handlingStrategy":"validation","validationCode":"String payload = json.getString(\"payload\");\nif (payload != null && !payload.matches(\"[A-Za-z0-9+/]*={0,2}\")) throw new IllegalArgumentException(\"payload must be standard base64\");","typeGuard":"static boolean isStandardBase64(String s) {\n  return s != null && !s.isEmpty() && s.matches(\"[A-Za-z0-9+/]+={0,2}\") && s.length() % 4 == 0;\n}","tryCatchPattern":"try {\n  Dto dto = json.mapTo(Dto.class);\n} catch (DecodeException e) {\n  if (e.getCause() instanceof InvalidFormatException) {\n    // locate offending field via ife.getPathReference()\n  }\n}","preventionTips":["Encode with Base64.getEncoder() (not getUrlEncoder) when serializing for Vert.x DTOs.","Add a unit test round-tripping every byte[] field through JSON.","Normalize cross-language base64url input before deserialization."],"tags":["json","base64","deserialization","bytearray"],"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-14T05:17:10.506Z"}