alibaba/nacos · error · IllegalArgumentException

Missing AgentResourceExt field: versionCatalog

Error message

Missing AgentResourceExt field: versionCatalog

What it means

The JSON stored in ai_resource.ext must contain a top-level 'versionCatalog' object. This validator (AgentResourceExtSerializer.validateCatalogShape) rejects any root JSON that omits it, because the version catalog is the mandatory carrier of an Agent's online Version list and protocol bindings. Without it the Agent resource is incomplete and cannot be serialized or deserialized.

Source

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

    private static void validateProviderShape(Map<?, ?> root) {
        if (!root.containsKey("provider")) {
            return;
        }
        Map<?, ?> provider = requireJsonObject(root.get("provider"), "provider");
        rejectUnknownFields(provider, PROVIDER_FIELDS, "AgentProvider");
        validateRequiredJsonText(provider, "name");
        validateOptionalJsonText(provider, "url");
    }
    
    private static void validateExtensionsShape(Map<?, ?> root) {
        if (root.containsKey("extensions")) {
            requireJsonObject(root.get("extensions"), "extensions");
        }
    }
    
    private static void validateCatalogShape(Map<?, ?> root) {
        if (!root.containsKey("versionCatalog")) {
            throw new IllegalArgumentException("Missing AgentResourceExt field: versionCatalog");
        }
        Map<?, ?> catalog = requireJsonObject(root.get("versionCatalog"), "versionCatalog");
        rejectUnknownFields(catalog, CATALOG_FIELDS, "AgentVersionCatalog");
        validateOptionalJsonText(catalog, "latestVersion");
        Object versionsValue = catalog.get("onlineVersions");
        if (!(versionsValue instanceof List)) {
            throw new IllegalArgumentException(
                "AgentVersionCatalog onlineVersions must be an array");
        }
        for (Object entryValue : (List<?>) versionsValue) {
            Map<?, ?> entry = requireJsonObject(entryValue, "versionCatalog entry");
            rejectUnknownFields(entry, CATALOG_ENTRY_FIELDS, "AgentVersionCatalogEntry");
            validateRequiredJsonText(entry, "version");
            validateStringArray(entry, "labels");
            validateStringArray(entry, "protocols");
        }
    }
    

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Add a 'versionCatalog' object to the root JSON with at least an 'onlineVersions' array.
2. If building programmatically, call resourceExt.setVersionCatalog(catalog) with a non-null AgentVersionCatalog that has at least one online version entry.
3. Validate with AgentResourceExtSerializer.validate(obj) before persisting to catch this earlier in the pipeline.

Example fix

// before
{"schemaVersion":1,"displayName":"my-agent"}
// after
{"schemaVersion":1,"displayName":"my-agent","versionCatalog":{"latestVersion":"1.0.0","onlineVersions":[{"version":"1.0.0","labels":[],"protocols":["a2a"]}]}}

if (resourceExt.getVersionCatalog() == null) {
    throw new IllegalStateException("versionCatalog is required before serialization");
}
AgentResourceExtSerializer.validate(resourceExt);

public static boolean hasValidCatalog(AgentResourceExt ext) {
    return ext != null && ext.getVersionCatalog() != null
        && ext.getVersionCatalog().getOnlineVersions() != null;
}

try {
    AgentResourceExtSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("versionCatalog")) {
        // log and provide a default empty catalog or reject the input
    }
    throw e;
}

When it happens

Trigger: Calling AgentResourceExtSerializer.deserialize(json) or serialize(obj) on JSON/object where the root object has no 'versionCatalog' key. Also triggered when persisting an AgentResourceExt whose getVersionCatalog() returns null (via the typed validate path → AgentModelValidator).

Common situations: Hand-editing the ai_resource.ext JSON column and forgetting the versionCatalog block; migrating from an older schema that did not require versionCatalog; building AgentResourceExt programmatically without setting the catalog; importing agent metadata from another system that uses a different shape.

Related errors

• AgentVersionCatalog onlineVersions must be an array
• {} must be an array
• {} must contain only strings
• {} must be a JSON object
• {} must be a string

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