alibaba/nacos · error · IllegalArgumentException

Invalid AgentResourceExt

Error message

Invalid AgentResourceExt

What it means

Thrown by deserialize() after JSON shape validation (validateJsonShape) passed but typed binding to AgentResourceExt.class failed. This means the raw JSON was structurally valid (object, known fields, right primitive kinds) yet Jackson could not map one or more values onto the typed model — e.g. an inner field that is a JSON object in a place where the model expects a typed POJO whose own properties mismatch, or a value that the model cannot coerce. The wrapped NacosDeserializationException carries the exact Jackson path.

Source

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

            return JacksonUtils.toJson(toStorageProjection(resourceExt));
        } catch (NacosSerializationException e) {
            throw new IllegalArgumentException("Unable to serialize AgentResourceExt", e);
        }
    }
    
    /**
     * Deserialize and validate Agent resource extension data.
     *
     * @param json JSON read from {@code ai_resource.ext}
     * @return deserialized extension object
     */
    public static AgentResourceExt deserialize(String json) {
        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);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Inspect the wrapped NacosDeserializationException cause — its message names the offending JSON path and the target type.
2. Confirm the writer and reader Nacos versions agree on the AgentResourceExt sub-model; if a mixed-version cluster wrote the row, fix or re-publish the agent from a node whose model matches the stored JSON.
3. Round-trip the suspect JSON through AgentResourceExtSerializer.serialize(AgentResourceExtSerializer.deserialize(json)) on a known-good node to find the smallest failing fragment.
4. If the row is corrupt, re-publish the agent (create/update via the AI admin API) with a well-formed ext payload to overwrite ai_resource.ext.

Example fix

// before: a stored ext whose provider was written as an array
{"schemaVersion":1,"provider":["acme","https://acme.io"],"versionCatalog":{"onlineVersions":[{"version":"1.0.0"}]}}
// after: provider must be a JSON object matching AgentProvider
{"schemaVersion":1,"provider":{"name":"acme","url":"https://acme.io"},"versionCatalog":{"onlineVersions":[{"version":"1.0.0"}]}}

// Before persisting, round-trip to confirm the typed model binds
try {
    AgentResourceExtSerializer.deserialize(AgentResourceExtSerializer.serialize(resourceExt));
} catch (IllegalArgumentException e) {
    // surface a domain error to the API caller with the offending field
    throw new AgentExtBindingException("ext cannot be bound to AgentResourceExt", e);
}

try {
    AgentResourceExt ext = AgentResourceExtSerializer.deserialize(rawJson);
} catch (IllegalArgumentException e) {
    // e.getMessage() == "Invalid AgentResourceExt"; e.getCause() is NacosDeserializationException with the JSON path
    log.warn("rejecting agent ext: {}", e.getCause().getMessage());
    throw new AgentExtMalformedException(rawJson, e);
}

When it happens

Trigger: Called from AgentPersistenceService.deserialize of the ai_resource.ext column when reading an agent row (AgentPersistenceService.java:758, 853, 880, 1309, 1333). Happens when a stored ext payload was written by an older/newer Nacos version whose AgentResourceExt sub-model (AgentProvider, AgentVersionCatalog, AgentVersionCatalogEntry) differs from the running server, or when a value's JSON type is legal at the loose Map layer but illegal for the typed field (e.g. provider given as a JSON array, or versionCatalog.onlineVersions entries missing the version key).

Common situations: Schema/model drift between the writer and reader (rolling upgrade, mixed-version cluster), hand-edited ai_resource.ext rows in the DB, a future schemaVersion=2 payload read by a v1 server, or a partial/incomplete agent record persisted by a buggy client.

Related errors

• Invalid persisted Agent tags
• Persisted Agent tags must be a JSON array
• Persisted Agent tags must contain only strings
• Stored Agent versionInfo must not be null
• AgentResourceExt JSON must not be empty

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