{"id":"e413a00a1a8def1b","repo":"google/gson","slug":"not-a-json-array-this","errorCode":null,"errorMessage":"Not a JSON Array: {this}","messagePattern":"Not a JSON Array: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"gson/src/main/java/com/google/gson/JsonElement.java","lineNumber":178,"sourceCode":"    if (isJsonObject()) {\n      return (JsonObject) this;\n    }\n    throw new IllegalStateException(\"Not a JSON Object: \" + this);\n  }\n\n  /**\n   * Convenience method to get this element as a {@link JsonArray}. If this element is of some other\n   * type, an {@link IllegalStateException} will result. Hence it is best to use this method after\n   * ensuring that this element is of the desired type by calling {@link #isJsonArray()} first.\n   *\n   * @return this element as a {@link JsonArray}.\n   * @throws IllegalStateException if this element is of another type.\n   */\n  public JsonArray getAsJsonArray() {\n    if (isJsonArray()) {\n      return (JsonArray) this;\n    }\n    throw new IllegalStateException(\"Not a JSON Array: \" + this);\n  }\n\n  /**\n   * Convenience method to get this element as a {@link JsonPrimitive}. If this element is of some\n   * other type, an {@link IllegalStateException} will result. Hence it is best to use this method\n   * after ensuring that this element is of the desired type by calling {@link #isJsonPrimitive()}\n   * first.\n   *\n   * @return this element as a {@link JsonPrimitive}.\n   * @throws IllegalStateException if this element is of another type.\n   */\n  public JsonPrimitive getAsJsonPrimitive() {\n    if (isJsonPrimitive()) {\n      return (JsonPrimitive) this;\n    }\n    throw new IllegalStateException(\"Not a JSON Primitive: \" + this);\n  }\n","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/google/gson/blob/8b8628c65699bc4421696183c62ae0c1b9b281dc/gson/src/main/java/com/google/gson/JsonElement.java#L160-L196","documentation":"Thrown by JsonElement.getAsJsonArray() when the element is not a JsonArray. Like the other cast helpers it assumes the caller has already confirmed the shape.","triggerScenarios":"Calling element.getAsJsonArray() where the parsed value is an object, primitive, or null.","commonSituations":"A field that is a single object in one response and an array in another (a common XML-to-JSON / single-element-array quirk); a nullable list represented as JSON null; schema drift.","solutions":["Guard with element.isJsonArray() before getAsJsonArray().","If a field may be a single object OR an array, normalize both into a list.","Handle isJsonNull() for nullable lists.","Deserialize to List<T> and let Gson report shape errors structurally."],"exampleFix":"// before\nJsonArray a = el.getAsJsonArray(); // throws if not array\n// after\nif (el.isJsonArray()) {\n  JsonArray a = el.getAsJsonArray();\n} else if (el.isJsonObject()) {\n  // normalize single object to one-element list\n} else {\n  // handle null / primitive\n}","handlingStrategy":"type-guard","validationCode":"if (!element.isJsonArray()) {\n  throw new IllegalStateException(\"expected JSON array, got \" + element.getClass().getSimpleName());\n}\nJsonArray a = element.getAsJsonArray();","typeGuard":"JsonArray asArrayOrDefault(JsonElement e, JsonArray def) {\n  return e != null && e.isJsonArray() ? e.getAsJsonArray() : def;\n}","tryCatchPattern":"try {\n  JsonArray a = el.getAsJsonArray();\n} catch (IllegalStateException e) {\n  // tolerate shape drift: treat non-array as empty\n}","preventionTips":["Always isJsonArray() before getAsJsonArray().","Normalize single-object-vs-array fields explicitly.","Use List<T> deserialization for stable list schemas."],"tags":["gson","json-element","type-mismatch","parsing"],"analyzedSha":"8b8628c65699bc4421696183c62ae0c1b9b281dc","analyzedAt":"2026-08-04T19:12:22.202Z","schemaVersion":2}