{"record":{"id":"c3bf8230a1d95b61","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/310ac341f2f92a454b229bf21f70d2d18b2b6db7/gson/src/main/java/com/google/gson/JsonElement.java#L160-L196","documentation":"Thrown by JsonElement.getAsJsonArray() (JsonElement.java:178) as an IllegalStateException when the element is not a JsonArray. Returns (JsonArray) this only when isJsonArray() is true (this instanceof JsonArray); otherwise throws with the element's toString appended.","triggerScenarios":"Calling getAsJsonArray() on a JsonObject, JsonPrimitive, or JsonNull. Common: obj.get(\"items\").getAsJsonArray() where 'items' is null, a single object, or a scalar; or an API that returns a single object instead of a list when the list has one element.","commonSituations":"API returns a bare object instead of a list for singleton results (a frequent serialization quirk); a field is conditionally null; mixed-type arrays where code assumes an array at a given path.","solutions":["Guard with element.isJsonArray() (and null-check) before calling getAsJsonArray()","If the API may return either a single object or an array, normalize both into a list","Handle the null/JsonNull case explicitly","Use a typed POJO (e.g. List<Item>) via gson.fromJson so Gson tolerates single-vs-list shapes"],"exampleFix":"// before\nJsonArray items = root.get(\"items\").getAsJsonArray();\n// after\nJsonElement e = root.get(\"items\");\nList<JsonElement> items = new ArrayList<>();\nif (e != null && e.isJsonArray()) items = e.getAsJsonArray().asList();\nelse if (e != null && e.isJsonObject()) items.add(e);\n// else: missing/null -> empty list","handlingStrategy":"type-guard","validationCode":"JsonElement e = root.get(\"items\");\nboolean safe = (e != null && e.isJsonArray());","typeGuard":"static JsonArray asArray(JsonElement e) {\n    return (e != null && e.isJsonArray()) ? e.getAsJsonArray() : new JsonArray();\n}","tryCatchPattern":"try {\n    JsonArray a = element.getAsJsonArray();\n} catch (IllegalStateException ex) {\n    // message starts with \"Not a JSON Array:\"\n}","preventionTips":["Null-check and call isJsonArray() before getAsJsonArray()","For APIs that return a single object instead of a list, normalize both shapes into a list","Use a typed List<T> target with gson.fromJson"],"tags":["gson","json","type-cast","illegal-state"],"backgroundTag":null,"analyzedSha":"310ac341f2f92a454b229bf21f70d2d18b2b6db7","analyzedAt":"2026-08-10T02:58:47.455Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}