google/gson · error · IllegalArgumentException

TypeToken captured `null` as type argument; probably a compi

Error message

TypeToken captured `null` as type argument; probably a compiler / runtime bug

What it means

Thrown by verifyNoTypeVariable when the captured type argument is unexpectedly null. This is a defensive check for a known compiler/runtime bug (not a user mistake): the Eclipse JDT compiler and certain JDK builds (e.g. Java 11.0.18) return null for a type variable declared by a method of a local class. Gson surfaces it rather than silently producing a broken TypeToken.

Source

Thrown at gson/src/main/java/com/google/gson/reflect/TypeToken.java:155

        verifyNoTypeVariable(ownerType);
      }

      for (Type typeArgument : parameterizedType.getActualTypeArguments()) {
        verifyNoTypeVariable(typeArgument);
      }
    } else if (type instanceof WildcardType) {
      WildcardType wildcardType = (WildcardType) type;
      for (Type bound : wildcardType.getLowerBounds()) {
        verifyNoTypeVariable(bound);
      }
      for (Type bound : wildcardType.getUpperBounds()) {
        verifyNoTypeVariable(bound);
      }
    } else if (type == null) {
      // Occurs in Eclipse IDE and certain Java versions (e.g. Java 11.0.18) when capturing type
      // variable declared by method of local class, see
      // https://github.com/eclipse-jdt/eclipse.jdt.core/issues/975
      throw new IllegalArgumentException(
          "TypeToken captured `null` as type argument; probably a compiler / runtime bug");
    }
  }

  /** Returns the raw (non-generic) type for this type. */
  public final Class<? super T> getRawType() {
    return rawType;
  }

  /** Gets underlying {@code Type} instance. */
  public final Type getType() {
    return type;
  }

  /**
   * Check if this type is assignable from the given class object.
   *
   * @deprecated this implementation may be inconsistent with javac for types with wildcards.

View on GitHub (pinned to 8b8628c656)

Solutions

Refactor to avoid capturing a type variable in the TypeToken; pass an explicit Class/Type to TypeToken.getParameterized instead.
Switch the compiler from Eclipse ecj to javac for the affected module, or upgrade Eclipse JDT to a version with the fix (see eclipse-jdt/eclipse.jdt.core#975).
Upgrade the JDK to a build that does not exhibit the null type-argument regression.
As a last resort, set gson.allowCapturingTypeVariables=true which skips verifyNoTypeVariable entirely (note this disables the related type-variable guard too).

Example fix

// before (Eclipse ecj returns null for the type variable)
<T> void handle() {
  class Local {
    TypeToken<T> token = new TypeToken<T>() {}; // captures null -> throws
  }
}

// after
<T> void handle(Class<T> typeClass) {
  TypeToken<T> token = TypeToken.get(typeClass); // explicit, compiler-independent
}

Defensive patterns

Strategy: validation

Validate before calling

// Detect the compiler/runtime null-type-argument condition before constructing the token
Type superclass = myClass.getGenericSuperclass();
if (superclass instanceof ParameterizedType) {
  Type arg = ((ParameterizedType) superclass).getActualTypeArguments()[0];
  if (arg == null) {
    throw new IllegalStateException("Compiler returned null type argument; rebuild with javac or upgrade JDT");
  }
}

Try / catch

try {
  TypeToken<T> token = new TypeToken<T>() {};
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("captured `null`")) {
    // fall back to an explicit Class-based token
    token = TypeToken.get(fallbackClass);
  } else {
    throw e;
  }
}

Prevention

Avoid constructing TypeTokens that reference method-local type variables, especially under Eclipse ecj.
Build with javac in CI to catch ecj-specific reflection quirks.
Keep Eclipse JDT and JDK versions current to avoid the regression (eclipse.jdt.core#975).
Pass explicit Class<T> arguments to bypass reflective capture entirely.

When it happens

Trigger: Compiling with Eclipse JDT (ecj) and creating a TypeToken whose argument is a type variable declared by a method of a local (non-member) class. The reflective generic superclass returns null for the actual type argument, so verifyNoTypeVariable hits the `type == null` branch at TypeToken.java:155.

Common situations: Developers using Eclipse IDE or building with ecj who construct TypeTokens referencing method-local type variables; upgrading the JDK to a patched 11.0.x that changed type-variable reflection behavior; rarely reproduced under javac.

Related errors

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