What causes "Not a JSON Null: ${this}" in google/gson?

Guard with element.isJsonNull() before calling getAsJsonNull()

google/gson · warning · IllegalStateException

Not a JSON Null

Error message

Not a JSON Null: ${this}

What it means

Thrown by JsonElement.getAsJsonNull() (JsonElement.java:211) as an IllegalStateException when the element is not a JsonNull. Returns (JsonNull) this only when isJsonNull() is true. This method is typically used to assert/verify that a value is the JSON null literal.

Solutions

Guard with element.isJsonNull() before calling getAsJsonNull()
In most cases just call isJsonNull() directly and skip getAsJsonNull()
Re-check the schema: the field was expected to be null but is populated

Example fix

// before
JsonNull n = root.get("deleted_at").getAsJsonNull();
// after
boolean isNull = root.has("deleted_at") && root.get("deleted_at").isJsonNull();

Defensive patterns

Strategy: type-guard

Validate before calling

JsonElement e = root.get("deleted_at");
boolean isNull = (e != null && e.isJsonNull());

Type guard

static boolean valueIsNull(JsonElement e) {
    return e != null && e.isJsonNull();
}

Try / catch

try {
    JsonNull n = element.getAsJsonNull();
} catch (IllegalStateException ex) {
    // message starts with "Not a JSON Null:" -> element actually has a value
}

Prevention

Use isJsonNull() directly instead of getAsJsonNull() for checks
Distinguish absent (get returns null) from explicit null (get returns JsonNull)
Validate the schema when a field is expected to be null but carries a value

When it happens

Trigger: Calling getAsJsonNull() on any non-null element — a JsonObject, JsonArray, or JsonPrimitive. Often an assertion-style call meant to confirm a field is null when it actually carries a value.

Common situations: Validation logic that expects a field to be absent/null but the payload populates it; checking a deletion/absence marker that now has a value.

Related errors

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

Appendix: source

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

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

  /**
   * Convenience method to get this element as a boolean value.
   *
   * @return this element as a primitive boolean value.
   * @throws UnsupportedOperationException if this element is not a {@link JsonPrimitive} or {@link
   *     JsonArray}.
   * @throws IllegalStateException if this element is of the type {@link JsonArray} but contains
   *     more than a single element.
   */
  public boolean getAsBoolean() {
    throw new UnsupportedOperationException(getClass().getSimpleName());
  }

  /**
   * Convenience method to get this element as a {@link Number}.
   *

View on GitHub (pinned to 310ac341f2)