{"record":{"id":"9c5b03d17013456c","repo":"eclipse-vertx/vert.x","slug":"invalid-json-array-json","errorCode":null,"errorMessage":"Invalid JSON array: ${json}","messagePattern":"Invalid JSON array: (.+?)","errorType":"exception","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/json/JsonArray.java","lineNumber":61,"sourceCode":"public class JsonArray implements Iterable<Object>, ClusterSerializable, Shareable {\n\n  private List<Object> list;\n\n  /**\n   * Create an instance from a String of JSON, this string must be a valid array otherwise an exception will be thrown.\n   * <p/>\n   * If you are unsure of the value, you should use instead {@link Json#decodeValue(String)} and check the result is\n   * a JSON array.\n   *\n   * @param json the string of JSON\n   */\n  public JsonArray(String json) {\n    if (json == null) {\n      throw new NullPointerException();\n    }\n    fromJson(json);\n    if (list == null) {\n      throw new DecodeException(\"Invalid JSON array: \" + json);\n    }\n  }\n\n  /**\n   * Create an empty instance\n   */\n  public JsonArray() {\n    list = new ArrayList<>();\n  }\n\n  /**\n   * Create an instance from a List. The List is not copied.\n   *\n   * @param list the underlying backing list\n   */\n  public JsonArray(List list) {\n    if (list == null) {\n      throw new NullPointerException();","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/json/JsonArray.java#L43-L79","documentation":"The JsonArray(String) constructor parses the string with Jackson; if parsing succeeds but the result is not a JSON array (e.g. it is an object, string, number, or invalid token), the internal list stays null and Vert.x throws DecodeException(\"Invalid JSON array: <json>\").","triggerScenarios":"new JsonArray(string) where the string is empty, malformed, or contains a valid JSON value that is not an array (e.g. \"{\\\"a\\\":1}\" or \"42\").","commonSituations":"Passing a JSON object payload into JsonArray; truncated response body from an API; reading an empty file; string with BOM or whitespace-only content.","solutions":["Inspect the string: if it starts with '{', use new JsonObject(json) instead.","Trim whitespace/BOM and fix truncation before parsing.","Validate the payload is a JSON array first with the Jackson ObjectMapper readTree.","Wrap construction in try-catch on DecodeException for untrusted input."],"exampleFix":"// before\nJsonArray arr = new JsonArray(responseBody); // may be an object\n// after\nif (responseBody.trim().startsWith(\"[\")) {\n  JsonArray arr = new JsonArray(responseBody);\n} else {\n  JsonObject obj = new JsonObject(responseBody);\n}","handlingStrategy":"validation","validationCode":"boolean isJsonArray(String s) { return s != null && s.trim().startsWith(\"[\"); }","typeGuard":"JsonArray safeArray(String json) { return json != null && json.trim().startsWith(\"[\") ? new JsonArray(json) : null; }","tryCatchPattern":"try { arr = new JsonArray(json); } catch (DecodeException e) { /* log json preview, handle non-array */ }","preventionTips":["Check the first non-whitespace character before choosing JsonObject vs JsonArray","Trim BOM/whitespace from external strings before parsing","Validate API response Content-Type and shape against the contract"],"tags":["json","decode","jsonarray"],"backgroundTag":"json-decode-failed","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"}