google/gson · error · IllegalStateException

Not a JSON Array: {this}

Error message

Not a JSON Array: {this}

What it means

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.

Source

Thrown at gson/src/main/java/com/google/gson/JsonElement.java:178

    if (isJsonObject()) {
      return (JsonObject) this;
    }
    throw new IllegalStateException("Not a JSON Object: " + this);
  }

  /**
   * Convenience method to get this element as a {@link JsonArray}. If this element is of some other
   * type, an {@link IllegalStateException} will result. Hence it is best to use this method after
   * ensuring that this element is of the desired type by calling {@link #isJsonArray()} first.
   *
   * @return this element as a {@link JsonArray}.
   * @throws IllegalStateException if this element is of another type.
   */
  public JsonArray getAsJsonArray() {
    if (isJsonArray()) {
      return (JsonArray) this;
    }
    throw new IllegalStateException("Not a JSON Array: " + this);
  }

  /**
   * Convenience method to get this element as a {@link JsonPrimitive}. If this element is of some
   * other type, an {@link IllegalStateException} will result. Hence it is best to use this method
   * after ensuring that this element is of the desired type by calling {@link #isJsonPrimitive()}
   * first.
   *
   * @return this element as a {@link JsonPrimitive}.
   * @throws IllegalStateException if this element is of another type.
   */
  public JsonPrimitive getAsJsonPrimitive() {
    if (isJsonPrimitive()) {
      return (JsonPrimitive) this;
    }
    throw new IllegalStateException("Not a JSON Primitive: " + this);
  }

View on GitHub (pinned to 8b8628c656)

Solutions

1. Guard with element.isJsonArray() before getAsJsonArray().
2. If a field may be a single object OR an array, normalize both into a list.
3. Handle isJsonNull() for nullable lists.
4. Deserialize to List<T> and let Gson report shape errors structurally.

Example fix

// before
JsonArray a = el.getAsJsonArray(); // throws if not array
// after
if (el.isJsonArray()) {
  JsonArray a = el.getAsJsonArray();
} else if (el.isJsonObject()) {
  // normalize single object to one-element list
} else {
  // handle null / primitive
}

if (!element.isJsonArray()) {
  throw new IllegalStateException("expected JSON array, got " + element.getClass().getSimpleName());
}
JsonArray a = element.getAsJsonArray();

JsonArray asArrayOrDefault(JsonElement e, JsonArray def) {
  return e != null && e.isJsonArray() ? e.getAsJsonArray() : def;
}

try {
  JsonArray a = el.getAsJsonArray();
} catch (IllegalStateException e) {
  // tolerate shape drift: treat non-array as empty
}

When it happens

Trigger: Calling element.getAsJsonArray() where the parsed value is an object, primitive, or null.

Common situations: 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.

Related errors

• Not a JSON Object: {this}
• Not a JSON Primitive: {this}
• Array must have size 1, but has size {size}
• Not a JSON Null: {this}
• {getClass().getSimpleName()}

AI-assisted analysis of google/gson@8b8628c656 (2026-08-04). Data as JSON: /data/errors/e413a00a1a8def1b.json. Report an issue: GitHub.