alibaba/nacos · error · IllegalArgumentException

Labels must not identify editing or reviewing Versions

Error message

Labels must not identify editing or reviewing Versions

What it means

Thrown by validateVersionInfoCatalogConsistency when any entry in versionInfo.labels has a value equal to editingVersion or reviewingVersion. Labels are meant to point at online (referenceable) Versions; pointing a label at an in-flight editing/reviewing Version would expose unstable references to consumers.

Source

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

        String editingVersion = versionInfo.getEditingVersion();
        String reviewingVersion = versionInfo.getReviewingVersion();
        if (editingVersion != null && editingVersion.equals(reviewingVersion)) {
            throw new IllegalArgumentException(
                "editingVersion and reviewingVersion must identify different Versions");
        }
        Set<String> onlineVersionValues = new HashSet<String>();
        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);

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure every label value references an online Version, not the editing or reviewing Version.
Defer label repointing until after the target Version is published (appears in onlineVersions).
When promoting, clear or keep labels on the previous online Version until the new one is live.

Example fix

// before
versionInfo.getLabels().put("stable", versionInfo.getEditingVersion());
// after
versionInfo.getLabels().put("stable", someOnlineVersion);

Defensive patterns

Strategy: validation

Validate before calling

static void checkLabelsNotEditReview(AgentVersionInfo info) {
    String e = info.getEditingVersion(), r = info.getReviewingVersion();
    for (var v : info.getLabels().values()) {
        if (v.equals(e) || v.equals(r)) {
            throw new IllegalArgumentException(
                "Labels must not identify editing or reviewing Versions");
        }
    }
}

Type guard

static boolean labelsAvoidEditReview(AgentVersionInfo info) {
    String e = info.getEditingVersion(), r = info.getReviewingVersion();
    return info.getLabels().values().stream()
        .noneMatch(v -> v.equals(e) || v.equals(r));
}

Try / catch

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Labels must not identify")) {
        // repoint offending labels to an online Version
    }
}

Prevention

Only point labels at online Versions.
Defer label repointing until the target Version is published.
Run a pre-flight check that label values are all in the online set.

When it happens

Trigger: Setting a label such as labels["stable"] = versionInfo.editingVersion while that Version is still being edited; bulk-assigning all labels to the newest Version regardless of its lifecycle state.

Common situations: A promotion script that repoints every label to the just-uploaded Version before it is online; alias labels (latest, stable, canary) pointing at a Version mid-review.

Related errors

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