alibaba/nacos · error · IllegalArgumentException

Version catalog label does not match versionInfo

Error message

Version catalog label does not match versionInfo: {label}

What it means

Thrown by validateVersionInfoCatalogConsistency when an online catalog entry's label does not map back to that entry's Version in versionInfo.labels. Each non-latest label attached to an online Version in the catalog must, in versionInfo.labels, point to that same Version. This enforces bidirectional label consistency between the catalog and versionInfo.

Solutions

  1. For every label on every online catalog entry, ensure versionInfo.labels[label] == entry.version.
  2. Treat labels as a single source of truth: derive catalog entry labels from versionInfo.labels (or vice versa) rather than editing both independently.
  3. After any label move, run a reconciliation pass that re-derives catalog entry labels from versionInfo.

Example fix

// before
catalogEntry120.setLabels(List.of("stable")); versionInfo.getLabels().put("stable", "1.1.0");
// after
catalogEntry120.setLabels(List.of("stable")); versionInfo.getLabels().put("stable", "1.2.0");
Defensive patterns

Strategy: validation

Validate before calling

static void checkCatalogLabelsMapBack(AgentVersionInfo info, AgentVersionCatalog catalog) {
    for (var entry : catalog.getOnlineVersions()) {
        for (String label : entry.getLabels()) {
            String mapped = info.getLabels().get(label);
            if (!entry.getVersion().equals(mapped)) {
                throw new IllegalArgumentException(
                    "Version catalog label does not match versionInfo: " + label);
            }
        }
    }
}

Type guard

static boolean catalogLabelsMapBack(AgentVersionInfo info, AgentVersionCatalog catalog) {
    for (var entry : catalog.getOnlineVersions()) {
        for (String label : entry.getLabels()) {
            if (!entry.getVersion().equals(info.getLabels().get(label))) return false;
        }
    }
    return true;
}

Try / catch

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Version catalog label does not match")) {
        // rebuild versionInfo.labels from catalog entry labels
    }
}

Prevention

When it happens

Trigger: A catalog entry for Version 1.2.0 carries label "stable", but versionInfo.labels["stable"] = "1.1.0" (or is absent). This mismatch means the catalog advertises a label that versionInfo resolves to a different Version.

Common situations: Reassigning a label in versionInfo during a canary shift without updating which catalog entry carries the label; merging two independently-edited halves of the model.

Related errors

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

Appendix: source

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

                || 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;
            }
            boolean presentInCatalog = false;
            for (AgentVersionCatalogEntry entry : onlineVersions) {
                if (entry.getVersion().equals(label.getValue())
                    && entry.getLabels().contains(label.getKey())) {
                    presentInCatalog = true;
                    break;
                }
            }
            if (!presentInCatalog) {

View on GitHub (pinned to 9b989acdf1)