alibaba/nacos · error · IllegalArgumentException

Online Version label is missing from versionCatalog: {label.

Error message

Online Version label is missing from versionCatalog: {label.key}

What it means

Thrown by validateVersionInfoCatalogConsistency for the reverse direction of error 491: when versionInfo.labels contains a (non-latest) entry whose value is an online Version, but the catalog entry for that Version does not list that label key. The label must exist on both sides; an online Version referenced by a label must advertise that label in the catalog.

Source

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

                        "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) {
                throw new IllegalArgumentException(
                    "Online Version label is missing from versionCatalog: " + label.getKey());
            }
        }
    }
    
    private static void validateCatalogLabels(List<String> labels, Set<String> allLabels) {
        requireNonNull(labels, "versionCatalog.labels");
        Set<String> entryLabels = new HashSet<String>();
        for (String label : labels) {
            AgentValidationUtils.validateNonLatestLabel(label);
            if (!entryLabels.add(label) || !allLabels.add(label)) {
                throw new IllegalArgumentException("Duplicate Version label: " + label);
            }
        }
    }
    
    private static void validateProtocols(List<String> protocols, String fieldName) {
        requireNonNull(protocols, fieldName);

View on GitHub (pinned to 9b989acdf1)

Solutions

For each non-latest versionInfo label whose value is an online Version, add that label key to the matching catalog entry's labels list.
Generate catalog entry labels directly from versionInfo.labels (invert the map) so the two cannot drift.
Run a bidirectional reconciliation: every label-value pair must appear on both the versionInfo side and the catalog entry side.

Example fix

// before
versionInfo.getLabels().put("canary", "1.4.0"); entry140.setLabels(List.of());
// after
versionInfo.getLabels().put("canary", "1.4.0"); entry140.setLabels(List.of("canary"));

Defensive patterns

Strategy: validation

Validate before calling

static void checkVersionInfoLabelsAdvertised(AgentVersionInfo info, AgentVersionCatalog catalog) {
    Map<String, AgentVersionCatalogEntry> byVersion = new HashMap<>();
    for (var en : catalog.getOnlineVersions()) byVersion.put(en.getVersion(), en);
    for (var label : info.getLabels().entrySet()) {
        if ("latest".equals(label.getKey())) continue;
        AgentVersionCatalogEntry en = byVersion.get(label.getValue());
        if (en != null && !en.getLabels().contains(label.getKey())) {
            throw new IllegalArgumentException(
                "Online Version label is missing from versionCatalog: " + label.getKey());
        }
    }
}

Type guard

static boolean versionInfoLabelsAdvertised(AgentVersionInfo info, AgentVersionCatalog catalog) {
    Map<String, AgentVersionCatalogEntry> byVersion = new HashMap<>();
    for (var en : catalog.getOnlineVersions()) byVersion.put(en.getVersion(), en);
    return info.getLabels().entrySet().stream().allMatch(l ->
        "latest".equals(l.getKey())
        || byVersion.get(l.getValue()) == null
        || byVersion.get(l.getValue()).getLabels().contains(l.getKey()));
}

Try / catch

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Online Version label is missing")) {
        // add missing label keys to the matching catalog entries
    }
}

Prevention

Generate catalog entry labels by inverting versionInfo.labels so the two cannot drift.
Run a bidirectional reconciliation before submission.
Never edit versionInfo.labels and catalog entry labels through independent code paths.

When it happens

Trigger: versionInfo.labels["canary"] = "1.4.0" and 1.4.0 is in onlineVersions, but the catalog entry for 1.4.0 has no "canary" in its labels list. The versionInfo promises a label the catalog does not surface.

Common situations: Adding a label in versionInfo to route traffic but forgetting to attach it to the catalog entry; importing versionInfo from one system and the catalog from another.

Related errors

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