alibaba/nacos · error · IllegalArgumentException

AgentResourceExt must not be null

Error message

AgentResourceExt must not be null

What it means

validate() (and therefore serialize()) rejects a null AgentResourceExt outright. The serializer is strict: it never silently treats null as an empty extension, because ai_resource.ext must always carry at least schemaVersion and versionCatalog. A null here is a programming contract violation, not a data condition.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentResourceExtSerializer.java:118

        validateJsonShape(json);
        final AgentResourceExt result;
        try {
            result = JacksonUtils.toObj(json, AgentResourceExt.class);
        } catch (NacosDeserializationException e) {
            throw new IllegalArgumentException("Invalid AgentResourceExt", e);
        }
        validate(result);
        return result;
    }
    
    /**
     * Validate Agent resource extension data against schema version 1.
     *
     * @param resourceExt typed extension object
     */
    public static void validate(AgentResourceExt resourceExt) {
        if (resourceExt == null) {
            throw new IllegalArgumentException("AgentResourceExt must not be null");
        }
        if (!Integer.valueOf(AgentResourceExt.SCHEMA_VERSION)
            .equals(resourceExt.getSchemaVersion())) {
            throw new IllegalArgumentException("AgentResourceExt schemaVersion must be "
                + AgentResourceExt.SCHEMA_VERSION);
        }
        validateOptionalCodePointLength(resourceExt.getDisplayName(),
            MAX_DISPLAY_NAME_LENGTH, "displayName");
        validateOptionalAbsoluteUri(resourceExt.getIconUrl(), "iconUrl");
        validateProvider(resourceExt.getProvider());
        validateExtensions(resourceExt.getExtensions());
        validateCatalog(resourceExt.getVersionCatalog());
    }
    
    private static void validateProvider(AgentProvider provider) {
        if (provider == null) {
            return;
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure the AgentResourceExt is always constructed before serialize: build it with schemaVersion and a versionCatalog at minimum.
2. If a null ext is legitimately possible at the call site, guard with an explicit null check that returns/throws a domain-specific error instead of calling serialize(null).
3. Search callers of AgentResourceExtSerializer.serialize for places that pass a possibly-null expression and fix the data flow upstream.

Example fix

// before
result.setExt(AgentResourceExtSerializer.serialize(resourceExt)); // resourceExt may be null

// after
if (resourceExt == null) {
    throw new IllegalArgumentException("agent resourceExt is required");
}
result.setExt(AgentResourceExtSerializer.serialize(resourceExt));

java.util.Objects.requireNonNull(resourceExt, "agent resourceExt must not be null");
if (resourceExt.getSchemaVersion() == null || resourceExt.getVersionCatalog() == null) {
    throw new IllegalArgumentException("resourceExt is incomplete");
}
AgentResourceExtSerializer.serialize(resourceExt);

try {
    AgentResourceExtSerializer.serialize(resourceExt);
} catch (IllegalArgumentException e) {
    if ("AgentResourceExt must not be null".equals(e.getMessage())) {
        throw new AgentExtMissingException();
    }
    throw e;
}

When it happens

Trigger: AgentPersistenceService.serialize(...) is called with a null ext before persisting (AgentPersistenceService.java:970, 1287), e.g. an agent create/update handler built the AgentResourceExt object but a code path left it null, or a caller passed the result of a method that returned null on a lookup miss straight into serialize.

Common situations: New agent API handler that forgets to populate the ext object, a refactor that changed the builder to return null on validation failure upstream, or a test/migration that constructs an Agent record without its ext.

Related errors

• Agent replacement must not be null
• Agent publish request must not be null
• Online Agent Version must contain callInterfaces
• Agent Version namespaceId does not match request
• Agent Version agentName does not match request

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