alibaba/nacos · error · IllegalArgumentException

AgentVersionCatalog onlineVersions must be an array

Error message

AgentVersionCatalog onlineVersions must be an array

What it means

Inside the mandatory 'versionCatalog' object, the 'onlineVersions' field must be a JSON array. This check (validateCatalogShape, line 341) fires when onlineVersions is present but is a string, number, object, or null instead of an array. Each array element must itself be an object describing one online Agent Version.

Source

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

        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");
        }
    }
    
    private static void validateStringArray(Map<?, ?> object, String field) {
        Object value = object.get(field);
        if (!(value instanceof List)) {
            throw new IllegalArgumentException(field + " must be an array");
        }
        for (Object item : (List<?>) value) {
            if (!(item instanceof String)) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Change versionCatalog.onlineVersions to a JSON array of objects, each containing 'version', 'labels', and 'protocols'.
Ensure your JSON serializer emits a List/Array type for onlineVersions, not a Map or String.
Run the JSON through AgentResourceExtSerializer.deserialize() in a test to validate the shape before deployment.

Example fix

// before
"versionCatalog":{"onlineVersions":{"version":"1.0.0"}}
// after
"versionCatalog":{"onlineVersions":[{"version":"1.0.0","labels":[],"protocols":["a2a"]}]}

Defensive patterns

Strategy: validation

Validate before calling

Object onlineVersions = catalogRaw.get("onlineVersions");
if (!(onlineVersions instanceof List)) {
    throw new IllegalArgumentException("onlineVersions must be a JSON array before deserialization");
}

Type guard

public static boolean isOnlineVersionsArray(Map<?,?> catalog) {
    return catalog != null && catalog.get("onlineVersions") instanceof List;
}

Try / catch

try {
    AgentResourceExtSerializer.deserialize(json);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("onlineVersions must be an array")) {
        // fix the JSON shape or reject the record
    }
    throw e;
}

Prevention

Always serialize onlineVersions as a JSON array, never as a string or object.
Validate the raw JSON shape with a schema validator before calling deserialize().
Use JacksonUtils to serialize typed DTOs so array types are preserved.

When it happens

Trigger: Deserializing ai_resource.ext JSON where versionCatalog.onlineVersions is a non-array type (e.g. a string "1.0.0" or an object instead of a list). Triggered during AgentResourceExtSerializer.deserialize → validateJsonShape → validateCatalogShape.

Common situations: Typos in hand-written JSON; tools that serialize onlineVersions as a comma-separated string; schema drift from an upstream system that sends versions as a map keyed by version string instead of an array.

Related errors

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