alibaba/nacos · error · IllegalArgumentException

Duplicate protocol for Agent Version {}: {}

Error message

Duplicate protocol for Agent Version {}: {}

What it means

Each online Agent Version must declare a unique set of protocols — no protocol string may appear twice for the same version. The AgentVersionCatalogBuilder.validateAndCopyProtocols method (line 123) throws this when a duplicate protocol is detected while building the unique-protocol copy. The error message includes the version and the duplicated protocol string.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/metadata/AgentVersionCatalogBuilder.java:124

    private static Map<String, List<String>> validateAndCopyProtocols(
        Map<String, List<String>> onlineVersionProtocols) {
        Map<String, List<String>> result = new LinkedHashMap<String, List<String>>();
        for (Map.Entry<String, List<String>> entry : onlineVersionProtocols.entrySet()) {
            String version = entry.getKey();
            AgentValidationUtils.validateVersion(version);
            List<String> protocols = entry.getValue();
            if (protocols == null || protocols.isEmpty()
                || protocols.size() > MAX_PROTOCOLS_PER_VERSION) {
                throw new IllegalArgumentException(
                    "Online Agent Version protocols must contain 1 to "
                        + MAX_PROTOCOLS_PER_VERSION + " values");
            }
            Set<String> uniqueProtocols = new HashSet<String>();
            List<String> protocolCopy = new ArrayList<String>(protocols.size());
            for (String protocol : protocols) {
                AgentValidationUtils.validateProtocol(protocol);
                if (!uniqueProtocols.add(protocol)) {
                    throw new IllegalArgumentException(
                        "Duplicate protocol for Agent Version " + version + ": " + protocol);
                }
                protocolCopy.add(protocol);
            }
            result.put(version, protocolCopy);
        }
        return result;
    }
    
    private static Map<String, String> validateAndSortLabels(Map<String, String> labels) {
        for (Map.Entry<String, String> entry : labels.entrySet()) {
            AgentValidationUtils.validateLabel(entry.getKey());
            AgentValidationUtils.validateVersion(entry.getValue());
        }
        return sortLabels(labels);
    }
    
    private static Map<String, String> sortLabels(Map<String, String> labels) {

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Deduplicate the protocol list before registering: new LinkedHashSet<>(protocols) then new ArrayList<>(set).
  2. Audit the client code that assembles the protocols list to ensure each protocol is added at most once.
  3. Log the final protocol list before submission to catch duplicates during development.

Example fix

// before
List<String> protocols = Arrays.asList("a2a", "mcp", "a2a");
// after
List<String> protocols = new ArrayList<>(new LinkedHashSet<>(Arrays.asList("a2a", "mcp", "a2a")));
Defensive patterns

Strategy: validation

Validate before calling

for (Map.Entry<String,List<String>> entry : onlineVersionProtocols.entrySet()) {
    Set<String> seen = new HashSet<>();
    for (String p : entry.getValue()) {
        if (!seen.add(p)) {
            throw new IllegalArgumentException("Duplicate protocol for " + entry.getKey() + ": " + p);
        }
    }
}

Type guard

public static boolean hasUniqueProtocols(Map<String,List<String>> map) {
    for (Map.Entry<String,List<String>> entry : map.entrySet()) {
        if (new HashSet<>(entry.getValue()).size() != entry.getValue().size()) return false;
    }
    return true;
}

Try / catch

try {
    AgentVersionCatalogBuilder.build(onlineVersionProtocols, labels);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Duplicate protocol")) {
        // deduplicate: onlineVersionProtocols.put(v, new ArrayList<>(new LinkedHashSet<>(list)))
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling AgentVersionCatalogBuilder.build() where a version's protocol list contains the same string twice, e.g. ["a2a","a2a"] or ["mcp","MCP"] (case-sensitive, so "mcp" and "MCP" are distinct). This is an internal server-side validation.

Common situations: Client registration code that concatenates protocol lists from multiple sources without deduplication; merging configurations that both specify the same protocol; copy-paste errors in protocol list construction.

Related errors

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