alibaba/nacos · error · IllegalArgumentException

{fieldName} must contain 1 to {MAX_CALL_INTERFACES} values

Error message

{fieldName} must contain 1 to {MAX_CALL_INTERFACES} values

What it means

Thrown by validateProtocols when a protocols list is empty or contains more than MAX_CALL_INTERFACES (16) values. This validates the protocols field of a catalog entry (fieldName = "versionCatalog.protocols"). Each online Version must declare at least one protocol and at most 16. An empty protocols list is invalid because a Version must be callable.

Source

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

            }
        }
    }
    
    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);
            }
        }
    }
    
    private static void validateCallInterfaces(String namespaceId, String agentName,
        List<AgentCallInterface> callInterfaces) {
        requireNonNull(callInterfaces, "callInterfaces");
        if (callInterfaces.isEmpty() || callInterfaces.size() > MAX_CALL_INTERFACES) {
            throw new IllegalArgumentException(
                "callInterfaces must contain 1 to " + MAX_CALL_INTERFACES + " items");
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Provide between 1 and 16 protocols for each catalog entry.
2. Ensure the protocols list is non-empty: at least the primary protocol must be present.
3. If you have more than 16 protocol variants, split the Version or drop redundant aliases.

Example fix

// before
entry.setProtocols(List.of());
// after
entry.setProtocols(List.of("mcp"));

static List<String> checkProtocols(List<String> protocols, String fieldName) {
    if (protocols == null || protocols.isEmpty() || protocols.size() > 16) {
        throw new IllegalArgumentException(fieldName + " must contain 1 to 16 values");
    }
    return protocols;
}

static boolean protocolsValid(List<String> protocols) {
    return protocols != null && !protocols.isEmpty() && protocols.size() <= 16;
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("must contain 1 to 16 values")) {
        // ensure at least the primary protocol is present
    }
}

When it happens

Trigger: A catalog entry with protocols = [] (Version with no callable interface); a catalog entry advertising 17+ protocols.

Common situations: Building a catalog entry and leaving protocols unset (defaults to empty list); aggregating many protocol variants under one Version.

Related errors

• tags exceeds {MAX_TAGS} items
• extensions exceeds {MAX_EXTENSIONS} entries
• Duplicate protocol: {protocol}
• callInterfaces must contain 1 to {MAX_CALL_INTERFACES} items
• 20002

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