alibaba/nacos · error · IllegalArgumentException

Agent Version catalog must use descending Version order

Q: What causes "Agent Version catalog must use descending Version order" in alibaba/nacos?

Sort onlineVersions in descending order before publishing: versions.sort((a,b) -> AgentVersionComparator.compare(b.getVersion(), a.getVersion())).

Error message

Agent Version catalog must use descending Version order

What it means

validateCatalog() requires onlineVersions to be strictly descending by semantic version (AgentVersionComparator). For each adjacent pair, the previous must compare greater-than the current; if previous <= current (equal or out of order) the ext is rejected. This enforces a canonical, newest-first ordering.

Source

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

                if (!(entry.getKey() instanceof String)) {
                    throw new IllegalArgumentException(
                        fieldName + " contains a non-string JSON object key");
                }
                validateJsonValue(entry.getValue(), fieldName);
            }
            return;
        }
        throw new IllegalArgumentException(fieldName + " is not a JSON value");
    }
    
    private static void validateCatalog(AgentVersionCatalog catalog) {
        AgentModelValidator.validateVersionCatalog(catalog);
        List<AgentVersionCatalogEntry> versions = catalog.getOnlineVersions();
        for (int i = 1; i < versions.size(); i++) {
            String previous = versions.get(i - 1).getVersion();
            String current = versions.get(i).getVersion();
            if (AgentVersionComparator.compare(previous, current) <= 0) {
                throw new IllegalArgumentException(
                    "Agent Version catalog must use descending Version order");
            }
        }
    }
    
    private static void validateOptionalAbsoluteUri(String value, String fieldName) {
        if (value == null) {
            return;
        }
        if (value.isEmpty() || value.codePointCount(0, value.length()) > MAX_URI_LENGTH) {
            throw new IllegalArgumentException("Invalid " + fieldName);
        }
        try {
            URI uri = new URI(value);
            if (!uri.isAbsolute()) {
                throw new IllegalArgumentException(fieldName + " must be an absolute URI");
            }
        } catch (URISyntaxException e) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Sort onlineVersions in descending order before publishing: versions.sort((a,b) -> AgentVersionComparator.compare(b.getVersion(), a.getVersion())).
De-duplicate versions before sorting.
Verify ordering with the same comparator you will publish under.

Example fix

// before
catalog.setOnlineVersions(List.of(v("1.0.0"), v("2.0.0"), v("1.5.0"))); // not descending

// after
List<AgentVersionCatalogEntry> vs = new ArrayList<>(List.of(v("1.0.0"), v("2.0.0"), v("1.5.0")));
vs.sort((a, b) -> AgentVersionComparator.compare(b.getVersion(), a.getVersion()));
catalog.setOnlineVersions(vs); // [2.0.0, 1.5.0, 1.0.0]

Defensive patterns

Strategy: validation

Validate before calling

List<AgentVersionCatalogEntry> vs = new ArrayList<>(catalog.getOnlineVersions());
vs.sort((a, b) -> com.alibaba.nacos.api.ai.utils.AgentVersionComparator.compare(b.getVersion(), a.getVersion()));
catalog.setOnlineVersions(vs);
// verify strictly descending
for (int i = 1; i < vs.size(); i++) {
    if (com.alibaba.nacos.api.ai.utils.AgentVersionComparator.compare(vs.get(i-1).getVersion(), vs.get(i).getVersion()) <= 0) {
        throw new IllegalStateException("duplicate or unordered versions");
    }
}

Try / catch

try {
    AgentResourceExtSerializer.serialize(resourceExt);
} catch (IllegalArgumentException e) {
    if ("Agent Version catalog must use descending Version order".equals(e.getMessage())) {
        sortCatalogDescending(catalog.getVersionCatalog());
        AgentResourceExtSerializer.serialize(resourceExt); // retry once
    } else throw e;
}

Prevention

Always sort onlineVersions descending by AgentVersionComparator before publish.
De-duplicate versions before sorting.
When appending a new version, insert at the head, not the tail.

When it happens

Trigger: An agent create/update whose versionCatalog.onlineVersions is unsorted, ascending, or contains duplicate versions. Triggered on serialize before persist and on deserialize when reading back.

Common situations: Appending a new version to the end of the list (which is oldest-first), inserting a patch version out of order, or duplicates from a merge.

Related errors

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