google/gson · error · IllegalArgumentException

Invalid nesting limit: " + limit

Error message

Invalid nesting limit: " + limit

What it means

Thrown by JsonReader.setNestingLimit(int) when the supplied limit is negative. The nesting limit defines how many arrays/objects may be open concurrently; a negative value is meaningless, so it is rejected immediately with IllegalArgumentException. Zero and positive values are accepted (0 means no structures may be opened at all).

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 8b8628c656)

Solutions

1. Pass a non-negative value; to disable the limit use a large number (default is 255).
2. If reading from config, map -1/unlimited to Integer.MAX_VALUE or to the DEFAULT_NESTING_LIMIT before calling setNestingLimit.
3. Validate the value with Math.max(0, configuredLimit) before passing it in.
4. Treat 0 as 'no nesting allowed' intentionally if you want to reject all structured JSON.

Example fix

// before
int configured = config.getInt("nesting", -1); // -1 means unlimited
reader.setNestingLimit(configured); // throws when -1

// after
int configured = config.getInt("nesting", JsonReader.DEFAULT_NESTING_LIMIT);
int safe = (configured < 0) ? Integer.MAX_VALUE : configured;
reader.setNestingLimit(safe);

int safeNestingLimit(int configured) {
  if (configured < 0) {
    // treat negative as 'unlimited' sentinel -> use a large positive value
    return Integer.MAX_VALUE;
  }
  return configured;
}
reader.setNestingLimit(safeNestingLimit(configured));

When it happens

Trigger: Calling reader.setNestingLimit(-1) or any value < 0. Common when the limit is computed from configuration or arithmetic that can go negative, or when -1 is used as a sentinel meaning 'unlimited' (which Gson does not support).

Common situations: Reading a nesting limit from a config file/property that defaults to -1 for 'unlimited'; computing limit = actualDepth - someOffset and underflowing; porting code from a library that treats -1 as infinity.

Related errors

• Invalid style: {style}
• Only combinations of \n and \r are allowed in newline.
• Only combinations of spaces and tabs are allowed in indent.
• Invalid version: {version}
• The date pattern '{pattern}' is not valid

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