alibaba/nacos · error · IllegalArgumentException

endpointSourceOrder must contain 1 or 2 sources

Error message

endpointSourceOrder must contain 1 or 2 sources

What it means

Thrown by validateEndpointSourceOrder when a CallInterface's endpointSourceOrder list is empty or has more than EndpointSource.values().length (2) entries. Each CallInterface must declare a non-empty source preference of at most the two available EndpointSource values, defining the order in which declared and discovered endpoints are tried.

Source

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

        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>();
        for (EndpointSource source : sourceOrder) {
            requireNonNull(source, "endpointSourceOrder item");
            if (!uniqueSources.add(source)) {
                throw new IllegalArgumentException("Duplicate Endpoint source: " + source);
            }
        }
    }
    
    private static void validateDeclaredEndpoints(String namespaceId, String agentName,
        String protocol, List<Endpoint> endpoints) {
        if (endpoints == null) {
            return;
        }
        if (endpoints.size() > MAX_DECLARED_ENDPOINTS) {
            throw new IllegalArgumentException(
                "declaredEndpoints exceeds " + MAX_DECLARED_ENDPOINTS + " items");

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set endpointSourceOrder to a non-empty list of 1 or 2 EndpointSource values.
2. For a purely declared-endpoint interface, use List.of(EndpointSource.DECLARED); to prefer discovered then declared, use List.of(DISCOVERED, DECLARED).
3. Never submit a CallInterface with an empty or null endpointSourceOrder.

Example fix

// before
callInterface.setEndpointSourceOrder(List.of());
// after
import com.alibaba.nacos.api.ai.model.agent.EndpointSource;
callInterface.setEndpointSourceOrder(List.of(EndpointSource.DECLARED));

static List<EndpointSource> checkSourceOrder(List<EndpointSource> order) {
    if (order == null || order.isEmpty() || order.size() > EndpointSource.values().length) {
        throw new IllegalArgumentException("endpointSourceOrder must contain 1 or 2 sources");
    }
    return order;
}

static boolean sourceOrderValid(List<EndpointSource> order) {
    return order != null && !order.isEmpty() && order.size() <= EndpointSource.values().length;
}

try {
    AgentModelValidator.validateCallInterface(ci);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("endpointSourceOrder must contain")) {
        ci.setEndpointSourceOrder(List.of(EndpointSource.DECLARED));
    }
}

When it happens

Trigger: A CallInterface with endpointSourceOrder = [] (no endpoint resolution strategy); a list with 3+ entries. Leaving the field unset so it defaults to an empty list.

Common situations: Building a CallInterface programmatically and forgetting to set endpointSourceOrder; assuming a server-side default exists (there is none — it is required).

Related errors

• 20002
• 20002
• 10000
• 10000
• callInterfaces must contain 1 to {MAX_CALL_INTERFACES} items

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