alibaba/nacos · error · IllegalArgumentException

Online Agent Version protocols must contain 1 to 16 values

Error message

Online Agent Version protocols must contain 1 to 16 values

What it means

Each online Agent Version must declare between 1 and 16 (MAX_PROTOCOLS_PER_VERSION) CallInterface protocols. The AgentVersionCatalogBuilder.validateAndCopyProtocols method (line 113) throws this when the protocols list for a version is null, empty, or exceeds 16 entries. This is a server-side validation during catalog derivation from Naming instance facts.

Source

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

            List<String> versionProtocols = protocolsByVersion.get(version);
            entry.setProtocols(Collections.unmodifiableList(versionProtocols));
            entries.add(entry);
        }
        catalog.setOnlineVersions(Collections.unmodifiableList(entries));
        AgentModelValidator.validateVersionCatalog(catalog);
        return new Result(catalog, normalizedLabels);
    }
    
    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;
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure every online version has at least 1 and at most 16 protocols in its registration.
If a version legitimately needs more than 16 protocols, split it into multiple version entries or discuss raising MAX_PROTOCOLS_PER_VERSION with maintainers.
Audit the client registration code to verify the protocols list is always populated before submission.

Example fix

// before
Map<String,List<String>> protocols = Map.of("1.0.0", Collections.emptyList());
AgentVersionCatalogBuilder.build(protocols, labels);
// after
Map<String,List<String>> protocols = Map.of("1.0.0", List.of("a2a","mcp"));
AgentVersionCatalogBuilder.build(protocols, labels);

Defensive patterns

Strategy: validation

Validate before calling

for (Map.Entry<String,List<String>> entry : onlineVersionProtocols.entrySet()) {
    List<String> protocols = entry.getValue();
    if (protocols == null || protocols.isEmpty() || protocols.size() > 16) {
        throw new IllegalArgumentException("Version " + entry.getKey()
            + " needs 1-16 protocols");
    }
}

Type guard

public static boolean hasValidProtocolCount(Map<String,List<String>> map) {
    for (List<String> protocols : map.values()) {
        if (protocols == null || protocols.isEmpty() || protocols.size() > 16) return false;
    }
    return true;
}

Try / catch

try {
    AgentVersionCatalogBuilder.build(onlineVersionProtocols, labels);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("1 to 16 values")) {
        // fix the protocol list for the offending version
    }
    throw e;
}

Prevention

Always populate at least one protocol per version before calling build().
Cap protocol list sizes at 16 in the client registration form.
Validate protocol counts in unit tests for each version registration.

When it happens

Trigger: Calling AgentVersionCatalogBuilder.build() with an onlineVersionProtocols map where a version key maps to null, an empty list, or a list with more than 16 protocol strings. This happens internally when the server reconstructs the catalog from registered Naming instances.

Common situations: An Agent Version registration that omitted all protocols; a client bug that registered zero protocols; an unusually broad Agent that supports more than 16 distinct protocols (unlikely but possible in large integrations).

Related errors

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