alibaba/nacos · error · IllegalArgumentException

subtype must not be null

Error message

subtype must not be null

What it means

Same constructor as 551; the subtype argument must not be null. Without a concrete subtype class there is nothing to deserialize into, so registration is rejected immediately.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/utils/json/NacosJsonSubtype.java:46

    private final Class<?> baseType;
    
    private final Class<?> subtype;
    
    private final String typeName;
    
    /**
     * Create a new subtype registration.
     *
     * @param baseType base type
     * @param subtype subtype class
     * @param typeName wire type name
     */
    public NacosJsonSubtype(Class<?> baseType, Class<?> subtype, String typeName) {
        if (baseType == null) {
            throw new IllegalArgumentException("baseType must not be null");
        }
        if (subtype == null) {
            throw new IllegalArgumentException("subtype must not be null");
        }
        if (typeName == null || typeName.length() == 0) {
            throw new IllegalArgumentException("typeName must not be empty");
        }
        this.baseType = baseType;
        this.subtype = subtype;
        this.typeName = typeName;
    }
    
    /**
     * Return base type.
     *
     * @return base type
     */
    public Class<?> getBaseType() {
        return baseType;
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Resolve and pass a non-null subtype Class.
2. Validate both class names resolve before constructing the tuple.
3. Skip registration on ClassNotFoundException and log a warning.

Example fix

// before
new NacosJsonSubtype(Base.class, unresolvedOrNull, "mySub");  // throws 552

// after
Class<?> sub = Class.forName(subtypeName);
new NacosJsonSubtype(Base.class, sub, "mySub");

if (subtype == null) {
    throw new IllegalStateException("subtype class could not be resolved");
}

When it happens

Trigger: Registering a subtype tuple where the concrete subtype Class is null (e.g. Class.forName failed and the result was forwarded).

Common situations: Plugin classloader cannot find the subtype class; typo in the configured subtype class name; conditional registration that skipped resolving the class.

Related errors

• baseType must not be null
• typeName must not be empty
• 20002
• PARAMETER_MISSING
• Agent Version storage descriptor must be a JSON object

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