google/gson · error · IllegalStateException

Not a JSON Object

Error message

Not a JSON Object: ${this}

What it means

Thrown by JsonElement.getAsJsonObject() (JsonElement.java:163) as an IllegalStateException when the element is not a JsonObject. The method is a convenience cast: it returns (JsonObject) this when isJsonObject() is true (i.e. this instanceof JsonObject), otherwise throws with the element's toString appended. The four JsonElement subtypes are JsonObject, JsonArray, JsonPrimitive and JsonNull; only JsonObject passes.

Solutions

1. Guard with element.isJsonObject() (and a Java null-check) before calling getAsJsonObject()
2. Handle the explicitly-null case with element.isJsonNull() / null separately
3. Inspect the raw JSON payload to confirm the field's actual runtime type
4. Deserialize directly into a typed POJO with gson.fromJson(json, MyClass.class) instead of manual tree navigation

Example fix

// before
JsonObject data = root.get("data").getAsJsonObject();
// after
JsonElement data = root.get("data");
if (data != null && data.isJsonObject()) {
    JsonObject obj = data.getAsJsonObject();
} else {
    // handle missing / wrong type / explicit null
}

JsonElement e = root.get("data");
boolean safe = (e != null && e.isJsonObject());
// only call getAsJsonObject() when `safe` is true

static JsonObject asObject(JsonElement e) {
    return (e != null && e.isJsonObject()) ? e.getAsJsonObject() : null;
}

try {
    JsonObject o = element.getAsJsonObject();
} catch (IllegalStateException ex) {
    // message starts with "Not a JSON Object:"
    // fall back: treat as missing/wrong-type
}

When it happens

Trigger: Calling getAsJsonObject() on a JsonElement that parsed to an array, primitive, or null. Most often obj.get("key").getAsJsonObject() where 'key' is explicitly JSON null (JsonNull) or where the API returned an array/string where an object was expected. Also JsonParser.parseString("[]").getAsJsonObject().

Common situations: A REST API changed a field from object to array or scalar; a field is conditionally null in the payload; loosely-typed third-party JSON; treating a one-object list as an object. Distinct from a Java NullPointerException (absent key returns null) — this fires on a present-but-wrong-type or JsonNull element.

Related errors

• Not a JSON Array
• Not a JSON Null
• Not a JSON Primitive
• ${getClass().getSimpleName()}
• Primitive is neither a number nor a string

AI-assisted analysis of google/gson@310ac341f2 (2026-08-10). Data as JSON: /api/errors/8fefa9bcead49be0. Report an issue: GitHub.

Appendix: source

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

   */
  public boolean isJsonNull() {
    return this instanceof JsonNull;
  }

  /**
   * Convenience method to get this element as a {@link JsonObject}. 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 #isJsonObject()}
   * first.
   *
   * @return this element as a {@link JsonObject}.
   * @throws IllegalStateException if this element is of another type.
   */
  public JsonObject getAsJsonObject() {
    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);
  }

  /**

View on GitHub (pinned to 310ac341f2)