google/gson · error · IllegalStateException

TypeToken must be created with a type argument: new TypeToke

Error message

TypeToken must be created with a type argument: new TypeToken<...>() {}; When using code shrinkers (ProGuard, R8, ...) make sure that generic signatures are preserved.\nSee " + TroubleshootingGuide.createUrl("type-token-raw")

What it means

TypeToken requires a captured generic type argument; it inspects its own generic superclass. If the immediate superclass is the raw TypeToken (no parameterization), Gson throws IllegalStateException pointing at ProGuard/R8 stripping generic signatures, or at a raw 'new TypeToken(){}' usage. A troubleshooting URL is included.

Source

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

   * Verifies that {@code this} is an instance of a direct subclass of TypeToken and returns the
   * type argument for {@code T} in {@link GsonTypes#canonicalize canonical form}.
   */
  private Type getTypeTokenTypeArgument() {
    Type superclass = getClass().getGenericSuperclass();
    if (superclass instanceof ParameterizedType) {
      ParameterizedType parameterized = (ParameterizedType) superclass;
      if (parameterized.getRawType() == TypeToken.class) {
        Type typeArgument = GsonTypes.canonicalize(parameterized.getActualTypeArguments()[0]);

        if (isCapturingTypeVariablesForbidden()) {
          verifyNoTypeVariable(typeArgument);
        }
        return typeArgument;
      }
    }
    // Check for raw TypeToken as superclass
    else if (superclass == TypeToken.class) {
      throw new IllegalStateException(
          "TypeToken must be created with a type argument: new TypeToken<...>() {}; When using code"
              + " shrinkers (ProGuard, R8, ...) make sure that generic signatures are preserved."
              + "\nSee "
              + TroubleshootingGuide.createUrl("type-token-raw"));
    }

    // User created subclass of subclass of TypeToken
    throw new IllegalStateException("Must only create direct subclasses of TypeToken");
  }

  private static void verifyNoTypeVariable(Type type) {
    if (type instanceof TypeVariable) {
      TypeVariable<?> typeVariable = (TypeVariable<?>) type;
      throw new IllegalArgumentException(
          "TypeToken type argument must not contain a type variable; captured type variable "
              + typeVariable.getName()
              + " declared by "
              + typeVariable.getGenericDeclaration()

View on GitHub (pinned to 8b8628c656)

Solutions

1. Always create TypeToken with an explicit type argument: 'new TypeToken<List<String>>(){}'.
2. Add ProGuard/R8 keep rules: '-keepattributes Signature' and keep your TypeToken subclasses.
3. Prefer the modern TypeToken.getParameterized(...) / TypeToken.get(...) APIs which do not rely on anonymous subclasses.

Example fix

// before
TypeToken<?> t = new TypeToken(){}; // raw, or signature stripped by R8

// after
TypeToken<List<String>> t = new TypeToken<List<String>>(){};
// or, signature-independent:
TypeToken<List<String>> t = TypeToken.getParameterized(List.class, String.class);
// proguard-rules.pro:
// -keepattributes Signature

boolean typeTokenHasArgument(TypeToken<?> t) {
  Type sc = t.getClass().getGenericSuperclass();
  return sc instanceof ParameterizedType && ((ParameterizedType) sc).getRawType() == TypeToken.class;
}

static boolean isParameterizedTypeTokenSubclass(Class<?> c) {
  Type sc = c.getGenericSuperclass();
  return sc instanceof ParameterizedType && ((ParameterizedType) sc).getRawType() == TypeToken.class;
}

// Construction-time failure; wrap TypeToken creation in a test rather than runtime try-catch.
try {
  TypeToken<List<String>> t = new TypeToken<List<String>>(){};
} catch (IllegalStateException e) {
  // switch to TypeToken.getParameterized(...)
}

When it happens

Trigger: Using 'new TypeToken(){}' with no type argument, or running on a code shrinker (ProGuard/R8) that removed the Signature attribute, so the generic superclass is observed as raw TypeToken.

Common situations: Android release builds with aggressive ProGuard/R8 rules; hand-written code that omits the generic argument; or tooling that drops Signature attributes.

Related errors

• Must only create direct subclasses of TypeToken
• Primitive type is not allowed
• Must specify owner type for {rawType}
• At most one lower bound is supported
• Exactly one upper bound must be specified

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