alibaba/nacos · error · IllegalArgumentException

callInterfaces must contain 1 to {MAX_CALL_INTERFACES} items

Error message

callInterfaces must contain 1 to {MAX_CALL_INTERFACES} items

What it means

Thrown by validateCallInterfaces when the callInterfaces list of an Agent Version detail is empty or contains more than MAX_CALL_INTERFACES (16) items. Each Version must declare at least one CallInterface (it must be callable) and at most 16. This is the container-level size check; per-item validation and per-protocol uniqueness run inside the loop.

Source

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

        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");
        }
        Set<String> protocols = new HashSet<String>();
        for (AgentCallInterface callInterface : callInterfaces) {
            validateCallInterface(namespaceId, agentName, callInterface);
            if (!protocols.add(callInterface.getProtocol())) {
                throw new IllegalArgumentException(
                    "Duplicate CallInterface protocol: " + callInterface.getProtocol());
            }
        }
    }
    
    private static void validateEndpointSourceOrder(List<EndpointSource> sourceOrder) {
        requireNonNull(sourceOrder, "endpointSourceOrder");
        if (sourceOrder.isEmpty() || sourceOrder.size() > EndpointSource.values().length) {
            throw new IllegalArgumentException("endpointSourceOrder must contain 1 or 2 sources");
        }
        Set<EndpointSource> uniqueSources = new HashSet<EndpointSource>();

View on GitHub (pinned to 9b989acdf1)

Solutions

Provide between 1 and 16 CallInterface entries per Version.
Ensure at least the primary CallInterface is present before submission.
If more than 16 are needed, consolidate interfaces that differ only by transport detail.

Example fix

// before
detail.setCallInterfaces(List.of());
// after
detail.setCallInterfaces(List.of(primaryCallInterface));

Defensive patterns

Strategy: validation

Validate before calling

static List<AgentCallInterface> checkCallInterfaces(List<AgentCallInterface> cis) {
    if (cis == null || cis.isEmpty() || cis.size() > 16) {
        throw new IllegalArgumentException("callInterfaces must contain 1 to 16 items");
    }
    return cis;
}

Type guard

static boolean callInterfacesValid(List<AgentCallInterface> cis) {
    return cis != null && !cis.isEmpty() && cis.size() <= 16;
}

Try / catch

try {
    AgentModelValidator.validateVersionDetail(detail);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("callInterfaces must contain")) {
        // add at least the primary CallInterface
    }
}

Prevention

Always populate at least one CallInterface per Version.
Cap the list at 16 at the producer.
Treat an empty callInterfaces list as a build error.

When it happens

Trigger: Submitting an AgentVersionDetail with callInterfaces = [] (a Version that cannot be called); a Version with 17+ CallInterface definitions.

Common situations: Creating a Version and forgetting to populate callInterfaces; migrating a config that split one interface into many protocol-specific ones.

Related errors

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