google/gson · error · IllegalArgumentException

Invalid nesting limit: {}

Error message

Invalid nesting limit: {}

What it means

Thrown by JsonReader.setNestingLimit(int) when limit < 0 (JsonReader.java:435-438). The nesting limit caps how many arrays/objects may be open at once and must be non-negative; a negative value has no meaningful interpretation and is rejected immediately. The default is 255.

Source

Thrown at gson/src/main/java/com/google/gson/stream/JsonReader.java:437

   *
   * <p>The nesting limit defines how many JSON arrays or objects may be open at the same time. For
   * example a nesting limit of 0 means no arrays or objects may be opened at all, a nesting limit
   * of 1 means one array or object may be open at the same time, and so on. So a nesting limit of 3
   * allows reading the JSON data <code>[{"a":[true]}]</code>, but for a nesting limit of 2 it would
   * fail at the inner {@code [true]}.
   *
   * <p>The nesting limit can help to protect against a {@link StackOverflowError} when recursive
   * {@link com.google.gson.TypeAdapter} implementations process deeply nested JSON data.
   *
   * <p>The default nesting limit is {@value #DEFAULT_NESTING_LIMIT}.
   *
   * @throws IllegalArgumentException if the nesting limit is negative.
   * @since 2.12.0
   * @see #getNestingLimit()
   */
  public final void setNestingLimit(int limit) {
    if (limit < 0) {
      throw new IllegalArgumentException("Invalid nesting limit: " + limit);
    }
    this.nestingLimit = limit;
  }

  /**
   * Returns the nesting limit of this reader.
   *
   * @since 2.12.0
   * @see #setNestingLimit(int)
   */
  public final int getNestingLimit() {
    return nestingLimit;
  }

  /**
   * Consumes the next token from the JSON stream and asserts that it is the beginning of a new
   * array.
   *

View on GitHub (pinned to 310ac341f2)

Solutions

1. Pass a non-negative value; use 0 to forbid any nesting or a value >= expected depth.
2. Clamp the computed limit with Math.max(0, computed) before calling setNestingLimit.
3. If the limit comes from config, validate and fall back to the default 255 when invalid.
4. Add a guard at the configuration boundary so the reader never sees a negative number.

Example fix

// before
reader.setNestingLimit(requestedDepth - safetyMargin);

// after
reader.setNestingLimit(Math.max(0, requestedDepth - safetyMargin));

int limit = Math.max(0, configuredLimit);
reader.setNestingLimit(limit);

static boolean isValidNestingLimit(int limit) {
  return limit >= 0;
}

try {
  reader.setNestingLimit(limit);
} catch (IllegalArgumentException e) {
  reader.setNestingLimit(0);
}

When it happens

Trigger: Calling reader.setNestingLimit(-1) or passing a computed value that underflows (e.g. derivedDepth - offset where offset exceeds depth). Also when a config property is misread as a negative integer.

Common situations: Reading nesting depth from external configuration with a typo or missing default; arithmetic that subtracts a safety margin and goes negative for shallow inputs; copying a value sourced from another reader without clamping.

Related errors

• {} requires {} type arguments, but got {}
• JsonReader is closed
• Expected a long but was {}{}
• Expected an int but was {}{}
• Nesting limit {} reached{}

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