alibaba/nacos · error · IllegalArgumentException

Duplicate Version label: {label}

Error message

Duplicate Version label: {label}

What it means

Thrown by validateCatalogLabels when a non-latest Version label appears more than once, either within a single catalog entry or across all entries (labels are globally unique across the whole catalog). The validator maintains a per-entry set and a shared all-labels set and rejects any label that fails to add to either. The "latest" label is excluded by validateNonLatestLabel.

Source

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

                    && 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);
        if (protocols.isEmpty() || protocols.size() > MAX_CALL_INTERFACES) {
            throw new IllegalArgumentException(
                fieldName + " must contain 1 to " + MAX_CALL_INTERFACES + " values");
        }
        Set<String> uniqueProtocols = new HashSet<String>();
        for (String protocol : protocols) {
            AgentValidationUtils.validateProtocol(protocol);
            if (!uniqueProtocols.add(protocol)) {
                throw new IllegalArgumentException("Duplicate protocol: " + protocol);
            }
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure each non-latest label key is used by at most one online catalog entry.
2. When moving a label, remove it from the previous entry before adding it to the new one.
3. Validate label uniqueness across the whole catalog before submission using a Set accumulator.

Example fix

// before
entryA.setLabels(List.of("stable")); entryB.setLabels(List.of("stable"));
// after
entryA.setLabels(List.of("stable")); entryB.setLabels(List.of("canary"));

static void checkCatalogLabelsUnique(List<AgentVersionCatalogEntry> entries) {
    Set<String> all = new HashSet<>();
    for (var entry : entries) {
        Set<String> perEntry = new HashSet<>();
        for (String label : entry.getLabels()) {
            if (!perEntry.add(label) || !all.add(label)) {
                throw new IllegalArgumentException("Duplicate Version label: " + label);
            }
        }
    }
}

static boolean catalogLabelsAreUnique(List<AgentVersionCatalogEntry> entries) {
    Set<String> all = new HashSet<>();
    for (var entry : entries) {
        Set<String> perEntry = new HashSet<>();
        for (String label : entry.getLabels()) {
            if (!perEntry.add(label) || !all.add(label)) return false;
        }
    }
    return true;
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Duplicate Version label")) {
        // remove the duplicated label from all but one entry
    }
}

When it happens

Trigger: Two catalog entries both carrying the label "stable"; one entry listing "stable" twice. Because labels resolve to exactly one Version, they must be globally unique.

Common situations: Moving a label from one Version to another by adding it to the new entry without removing it from the old; importing labels per-Version without enforcing global uniqueness.

Related errors

• Version catalog label does not match versionInfo: {label}
• Online Version label is missing from versionCatalog: {label.
• Duplicate tag: {tag}
• Labels must not identify editing or reviewing Versions
• latest label must be absent when no online Version exists

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