alibaba/nacos · error · IllegalArgumentException

NacosTypeReference must be created with generic type informa

Error message

NacosTypeReference must be created with generic type information.

What it means

NacosTypeReference captures its generic type argument by reflecting on the parameterized superclass. If it is subclassed raw (no type argument), the superclass is a plain Class and the cast to ParameterizedType would fail, so the constructor throws IllegalArgumentException to surface the misuse.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/utils/json/NacosTypeReference.java:39

/**
 * Captures generic type information for JSON deserialization without exposing
 * concrete JSON provider types.
 *
 * @param <T> target type
 * @author nacos
 */
public abstract class NacosTypeReference<T> {
    
    private final Type type;
    
    /**
     * Create a new type reference and capture generic type from subclass.
     */
    protected NacosTypeReference() {
        Type superClass = getClass().getGenericSuperclass();
        if (superClass instanceof Class) {
            throw new IllegalArgumentException(
                "NacosTypeReference must be created with generic type information.");
        }
        this.type = ((ParameterizedType) superClass).getActualTypeArguments()[0];
    }
    
    /**
     * Return captured generic type.
     *
     * @return captured type
     */
    public Type getType() {
        return type;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Always instantiate with a concrete parameterized type, e.g. new NacosTypeReference<List<Instance>>(){}.
Never subclass NacosTypeReference without supplying a type argument.
Add a compile-time check or unit test confirming getType() returns the expected ParameterizedType.

Example fix

// before
NacosTypeReference ref = new NacosTypeReference(){};  // raw -> throws 554

// after
NacosTypeReference<List<Instance>> ref = new NacosTypeReference<List<Instance>>(){};

Defensive patterns

Strategy: type-guard

Type guard

// Compile-time guard: always parameterize. A raw subclass is a programming error.
// new NacosTypeReference<List<Instance>>() {}  // OK
// new NacosTypeReference() {}                    // never do this

Prevention

Always instantiate NacosTypeReference with a concrete parameterized type.
Never subclass it raw; review any framework code that reflectively creates it.
Add a unit test asserting getType() returns a ParameterizedType.

When it happens

Trigger: Creating 'new NacosTypeReference(){}' with no generic argument, or subclassing it as a raw type; using a non-anonymous subclass that omits the type parameter.

Common situations: Copy-paste of a type-reference pattern without the '<>' generic; refactoring that introduced a raw subclass; framework code that tries to instantiate it reflectively without generics.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/9d964b1e46479b73. Report an issue: GitHub.