alibaba/nacos · error · IllegalArgumentException

latest label must be absent when no online Version exists

Error message

latest label must be absent when no online Version exists

What it means

Thrown by validateVersionInfoCatalogConsistency when versionCatalog.latestVersion is null (i.e., no online Version exists) but versionInfo.labels contains a "latest" entry. The latest label is a computed pointer to the catalog's latest online Version; if there are no online Versions, the label must not exist. This is the null-catalog branch paired with error 490.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:439

        for (AgentVersionCatalogEntry entry : onlineVersions) {
            onlineVersionValues.add(entry.getVersion());
        }
        if (onlineVersionValues.contains(editingVersion)
            || onlineVersionValues.contains(reviewingVersion)) {
            throw new IllegalArgumentException(
                "editingVersion and reviewingVersion must not identify online Versions");
        }
        for (Map.Entry<String, String> label : versionInfo.getLabels().entrySet()) {
            if (label.getValue().equals(editingVersion)
                || label.getValue().equals(reviewingVersion)) {
                throw new IllegalArgumentException(
                    "Labels must not identify editing or reviewing Versions");
            }
        }
        String latestLabelVersion = versionInfo.getLabels().get("latest");
        if (catalog.getLatestVersion() == null) {
            if (latestLabelVersion != null) {
                throw new IllegalArgumentException(
                    "latest label must be absent when no online Version exists");
            }
        } else if (!catalog.getLatestVersion().equals(latestLabelVersion)) {
            throw new IllegalArgumentException(
                "latest label and versionCatalog.latestVersion must match");
        }
        for (AgentVersionCatalogEntry entry : onlineVersions) {
            for (String label : entry.getLabels()) {
                if (!entry.getVersion().equals(versionInfo.getLabels().get(label))) {
                    throw new IllegalArgumentException(
                        "Version catalog label does not match versionInfo: " + label);
                }
            }
        }
        for (Map.Entry<String, String> label : versionInfo.getLabels().entrySet()) {
            if ("latest".equals(label.getKey())
                || !onlineVersionValues.contains(label.getValue())) {
                continue;

View on GitHub (pinned to 9b989acdf1)

Solutions

Remove the "latest" key from versionInfo.labels when there are no online Versions.
When transitioning the last online Version to offline, clear both catalog.latestVersion and labels["latest"] atomically.
On Agent creation with no online Versions, leave labels empty or exclude "latest".

Example fix

// before
catalog.setOnlineVersions(List.of()); versionInfo.getLabels().put("latest", "1.0.0");
// after
catalog.setOnlineVersions(List.of()); versionInfo.getLabels().remove("latest");

Defensive patterns

Strategy: validation

Validate before calling

static void syncLatestLabel(AgentVersionInfo info, AgentVersionCatalog catalog) {
    if (catalog.getLatestVersion() == null) {
        info.getLabels().remove("latest");
    }
}

Type guard

static boolean latestLabelConsistentWhenEmpty(AgentVersionInfo info, AgentVersionCatalog catalog) {
    return catalog.getLatestVersion() != null || info.getLabels().get("latest") == null;
}

Try / catch

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("latest label must be absent")) {
        agent.getVersionInfo().getLabels().remove("latest");
    }
}

Prevention

When the last online Version goes offline, clear labels["latest"] in the same mutation.
On Agent creation with no online Versions, leave labels empty.
Treat latest as derived from the catalog, never as independent state.

When it happens

Trigger: Submitting a payload where onlineVersions is empty (so latestVersion is null) but labels still carries "latest" -> some version from a prior state.

Common situations: Taking the last online Version offline but forgetting to remove the "latest" label; building a new Agent and seeding labels with a default "latest" entry before any Version is online.

Related errors

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