google/gson · error · IllegalStateException

Not a JSON Primitive

Error message

Not a JSON Primitive: ${this}

What it means

Thrown by JsonElement.getAsJsonPrimitive() (JsonElement.java:194) as an IllegalStateException when the element is not a JsonPrimitive (i.e. it is a JsonObject, JsonArray, or JsonNull). Returns (JsonPrimitive) this only when isJsonPrimitive() is true.

Solutions

1. Guard with element.isJsonPrimitive() (and null-check) before calling getAsJsonPrimitive()
2. Usually you can call the specific accessor (getAsString()/getAsInt()) directly once isJsonPrimitive() holds
3. Handle JsonNull explicitly
4. Prefer a typed POJO via gson.fromJson

Example fix

// before
JsonPrimitive p = root.get("version").getAsJsonPrimitive();
// after
JsonElement e = root.get("version");
if (e != null && e.isJsonPrimitive()) {
    JsonPrimitive p = e.getAsJsonPrimitive();
}

JsonElement e = root.get("version");
boolean safe = (e != null && e.isJsonPrimitive());

static JsonPrimitive asPrimitive(JsonElement e) {
    return (e != null && e.isJsonPrimitive()) ? e.getAsJsonPrimitive() : null;
}

try {
    JsonPrimitive p = element.getAsJsonPrimitive();
} catch (IllegalStateException ex) {
    // message starts with "Not a JSON Primitive:"
}

When it happens

Trigger: Calling getAsJsonPrimitive() on a container element or on JsonNull. E.g. obj.get("version").getAsJsonPrimitive() when 'version' is itself an object, an array, or explicitly null.

Common situations: Code that retrieves a leaf scalar but the field is unexpectedly structured (object/array); a field that is null; type assumptions about loosely-typed JSON.

Related errors

• Not a JSON Array
• Not a JSON Null
• Not a JSON Object
• ${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/ebc51296096dd51c. Report an issue: GitHub.

Appendix: source

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

      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);
  }

  /**
   * Convenience method to get this element as a {@link JsonNull}. 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 #isJsonNull()} first.
   *
   * @return this element as a {@link JsonNull}.
   * @throws IllegalStateException if this element is of another type.
   * @since 1.2
   */
  @CanIgnoreReturnValue // When this method is used only to verify that the value is JsonNull
  public JsonNull getAsJsonNull() {
    if (isJsonNull()) {
      return (JsonNull) this;
    }
    throw new IllegalStateException("Not a JSON Null: " + this);
  }

View on GitHub (pinned to 310ac341f2)