What causes "Must specify owner type for {rawType}" in google/gson?

Make the nested class static (preferred): add the 'static' modifier so no owner type is required.

google/gson · error · IllegalArgumentException

Must specify owner type for {rawType}

Error message

Must specify owner type for {rawType}

What it means

Thrown by ParameterizedTypeImpl's constructor (GsonTypes) when an owner type is null but requiresOwnerType(rawType) returns true. A non-static inner/nested class implicitly carries a reference to its enclosing instance, so a parameterized type for it (e.g. Outer<String>.Inner) must declare which enclosing instance type owns it. Omitting the owner produces an ill-formed ParameterizedType that Java reflection would never create.

Source

Thrown at gson/src/main/java/com/google/gson/internal/GsonTypes.java:523

      Class<?> rawTypeAsClass = (Class<?>) rawType;
      return !Modifier.isStatic(rawTypeAsClass.getModifiers())
          && rawTypeAsClass.getDeclaringClass() != null;
    }
    return false;
  }

  private static final class ParameterizedTypeImpl implements ParameterizedType {
    private final Type ownerType;

    private final Type rawType;

    private final Type[] typeArguments;

    ParameterizedTypeImpl(Type ownerType, Class<?> rawType, Type... typeArguments) {
      requireNonNull(rawType);

      if (ownerType == null && requiresOwnerType(rawType)) {
        throw new IllegalArgumentException("Must specify owner type for " + rawType);
      }

      this.ownerType = ownerType == null ? null : canonicalize(ownerType);
      this.rawType = canonicalize(rawType);
      this.typeArguments = typeArguments.clone();
      for (int t = 0, length = this.typeArguments.length; t < length; t++) {
        requireNonNull(this.typeArguments[t]);
        checkNotPrimitive(this.typeArguments[t]);
        this.typeArguments[t] = canonicalize(this.typeArguments[t]);
      }
    }

    @Override
    public Type[] getActualTypeArguments() {
      return typeArguments.clone();
    }

    @Override

View on GitHub (pinned to 8b8628c656)

Solutions

Make the nested class static (preferred): add the 'static' modifier so no owner type is required.
Supply the owner type when building the ParameterizedType, e.g. TypeToken.getParameterized(ownerType, Inner.class, args).
Move the nested class to a top-level class to avoid the owner-type requirement entirely.

Example fix

// before
class Outer<T> { class Inner { T value; } }
Type t = TypeToken.getParameterized(Outer.Inner.class, String.class).getType();

// after: make it static
class Outer<T> { static class Inner<T> { T value; } }

Defensive patterns

Strategy: validation

Validate before calling

static boolean needsOwner(Class<?> raw) {
  return !Modifier.isStatic(raw.getModifiers()) && raw.getDeclaringClass() != null;
}
// usage: if (needsOwner(rawType)) throw new IllegalStateException("provide ownerType or make static");

Type guard

null

Try / catch

try {
  TypeToken.getParameterized(Inner.class, args).getType();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("owner type")) {
    // fall back: make the nested class static or supply owner
    throw new IllegalStateException("Inner class needs ownerType; make it static", e);
  } else throw e;
}

Prevention

Prefer static nested classes for Gson model types.
When modeling inner generic classes, always pass the owner type explicitly.
Add a project convention: model classes must be top-level or static-nested.

When it happens

Trigger: Constructing a parameterized type for a non-static nested class (has a declaring class and is not static) without supplying ownerType. Triggered via TypeToken.getParameterized(Inner.class, ...) where Inner is an inner class, or by Gson resolving a field whose generic type is Outer<X>.Inner while resolving ownerType to null.

Common situations: Modeling JSON as a non-static inner class; using nested generic types like class Outer<T> { class Inner { T value; } } and serializing Inner directly; migration from static nested classes to inner classes without updating type tokens.

Related errors

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