alibaba/nacos · error · IllegalArgumentException

AgentVersionContent callInterfaces must contain 1 to {MAX_CA

Error message

AgentVersionContent callInterfaces must contain 1 to {MAX_CALL_INTERFACES} items

What it means

Thrown by validate when callInterfaces is null, empty, or contains more than MAX_CALL_INTERFACES (16) entries. Each Agent Version must expose at least one and at most 16 call interfaces (protocol bindings).

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionContentSerializer.java:158

    }
    
    private static void validate(AgentVersionContent content) {
        if (content == null) {
            throw new IllegalArgumentException("AgentVersionContent must not be null");
        }
        if (!AgentVersionContent.KIND.equals(content.getKind())) {
            throw new IllegalArgumentException("AgentVersionContent kind must be "
                + AgentVersionContent.KIND);
        }
        if (!Integer.valueOf(AgentVersionContent.SCHEMA_VERSION)
            .equals(content.getSchemaVersion())) {
            throw new IllegalArgumentException("AgentVersionContent schemaVersion must be "
                + AgentVersionContent.SCHEMA_VERSION);
        }
        List<AgentCallInterface> callInterfaces = content.getCallInterfaces();
        if (callInterfaces == null || callInterfaces.isEmpty()
            || callInterfaces.size() > MAX_CALL_INTERFACES) {
            throw new IllegalArgumentException(
                "AgentVersionContent callInterfaces must contain 1 to " + MAX_CALL_INTERFACES
                    + " items");
        }
        Set<String> protocols = new HashSet<String>();
        for (AgentCallInterface callInterface : callInterfaces) {
            AgentModelValidator.validateCallInterface(callInterface);
            if (!protocols.add(callInterface.getProtocol())) {
                throw new IllegalArgumentException(
                    "Duplicate CallInterface protocol: " + callInterface.getProtocol());
            }
        }
    }
    
    private static Map<String, Object> toStorageProjection(AgentVersionContent content) {
        Map<String, Object> result = new LinkedHashMap<String, Object>();
        result.put("kind", AgentVersionContent.KIND);
        result.put("schemaVersion", AgentVersionContent.SCHEMA_VERSION);
        List<Map<String, Object>> callInterfaces = new ArrayList<Map<String, Object>>();

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Ensure callInterfaces contains between 1 and 16 entries before serializing.
  2. Add at least one AgentCallInterface with a valid protocol, descriptor media type, and endpoint source order.
  3. If you need more than 16 protocols on one version, split into multiple versions or request a limit change via spec.

Example fix

// before
AgentVersionContent c = new AgentVersionContent(Collections.emptyList());

// after
AgentVersionContent c = new AgentVersionContent(List.of(callInterface));
Defensive patterns

Strategy: validation

Validate before calling

if (callInterfaces == null || callInterfaces.isEmpty() || callInterfaces.size() > 16) {
    throw new IllegalArgumentException("callInterfaces must be 1..16");
}

Prevention

When it happens

Trigger: Serializing/deserializing content with zero call interfaces, a null list, or more than 16. Occurs when a publisher submits a version with no protocols or attempts to register an excessive number of protocol bindings on one version.

Common situations: A draft Agent Version created before any protocol interface is defined (empty list), or an automated tool generating one callInterface per protocol variant and exceeding 16.

Related errors

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