google/gson · error · IllegalArgumentException

Invalid version: {version}

Error message

Invalid version: {version}

What it means

Thrown by GsonBuilder.setVersion(double) when the supplied version is NaN or negative. Versions drive the @Since and @Until field/class exclusion logic; NaN and negative numbers are meaningless as version ordinals and would break comparison. It is an IllegalArgumentException raised at configuration time, before any Gson instance is built.

Source

Thrown at gson/src/main/java/com/google/gson/GsonBuilder.java:207

  /**
   * Configures Gson to enable versioning support. Versioning support works based on the annotation
   * types {@link Since} and {@link Until}. It allows including or excluding fields and classes
   * based on the specified version. See the documentation of these annotation types for more
   * information.
   *
   * <p>By default versioning support is disabled and usage of {@code @Since} and {@code @Until} has
   * no effect.
   *
   * @param version the version number to use.
   * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
   * @throws IllegalArgumentException if the version number is NaN or negative
   * @see Since
   * @see Until
   */
  @CanIgnoreReturnValue
  public GsonBuilder setVersion(double version) {
    if (Double.isNaN(version) || version < 0.0) {
      throw new IllegalArgumentException("Invalid version: " + version);
    }
    excluder = excluder.withVersion(version);
    return this;
  }

  /**
   * Configures Gson to excludes all class fields that have the specified modifiers. By default,
   * Gson will exclude all fields marked {@code transient} or {@code static}. This method will
   * override that behavior.
   *
   * <p>This is a convenience method which behaves as if an {@link ExclusionStrategy} which excludes
   * these fields was {@linkplain #setExclusionStrategies(ExclusionStrategy...) registered with this
   * builder}.
   *
   * @param modifiers the field modifiers. You must use the modifiers specified in the {@link
   *     java.lang.reflect.Modifier} class. For example, {@link
   *     java.lang.reflect.Modifier#TRANSIENT}, {@link java.lang.reflect.Modifier#STATIC}.
   * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern

View on GitHub (pinned to 8b8628c656)

Solutions

1. Pass a valid non-negative finite double: setVersion(1.0), setVersion(2.5), or setVersion(0.0) to include everything.
2. If version comes from external config, validate it (Double.isFinite(v) && v >= 0.0) before calling setVersion, and default to 0.0 or skip setVersion entirely when unset.
3. Guard against NaN explicitly: if (Double.isNaN(v)) throw new IllegalArgumentException("version required").
4. Use a sentinel-to-meaningful mapping (e.g. -1 -> 0.0) rather than passing the sentinel through.

Example fix

// before: external config can yield NaN or negative
double v = parseVersion(config); // may be NaN
new GsonBuilder().setVersion(v).create(); // throws if NaN or < 0

// after: validate and default
GsonBuilder b = new GsonBuilder();
double v = parseVersion(config);
if (Double.isFinite(v) && v >= 0.0) {
  b.setVersion(v);
}
Gson gson = b.create();

// Validate version before calling setVersion
double v = parseVersion(config);
if (!Double.isFinite(v) || v < 0.0) {
  throw new IllegalArgumentException("Version must be finite and >= 0: " + v);
}
GsonBuilder b = new GsonBuilder();
if (v > 0) b.setVersion(v);
Gson gson = b.create();

static boolean isValidVersion(double v) {
  return Double.isFinite(v) && v >= 0.0;
}

When it happens

Trigger: Calling setVersion(Double.NaN); setVersion(-1.0); computing the version from external config that yields NaN (e.g. parsing failure returning NaN) or a negative sentinel; passing 0.0 is allowed, but any negative value throws.

Common situations: Config-driven version selection where the config is missing and defaults to NaN/-1; arithmetic that divides by zero producing NaN; sentinel values like -1 meaning 'unset' fed directly to setVersion; unit tests with placeholder versions.

Related errors

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

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