alibaba/nacos · error · IllegalArgumentException

declaredEndpoints exceeds {MAX_DECLARED_ENDPOINTS} items

Error message

declaredEndpoints exceeds {MAX_DECLARED_ENDPOINTS} items

What it means

Thrown by AgentModelValidator.validateDeclaredEndpoints when an Agent's CallInterface declares more than MAX_DECLARED_ENDPOINTS (64) static endpoints. The cap exists because declared endpoints are author-time configuration stored on the Agent resource, not a discovery mechanism; pushing large endpoint sets through the declared channel degrades storage and validation. The check fires before any individual endpoint is examined, so it aborts the whole validation.

Source

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

        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");
        }
        Set<EndpointNaturalKey> endpointKeys = new HashSet<EndpointNaturalKey>();
        for (Endpoint endpoint : endpoints) {
            validateEndpoint(endpoint);
            EndpointNaturalKey key = EndpointNaturalKey.of(namespaceId, agentName, protocol,
                endpoint);
            if (!endpointKeys.add(key)) {
                throw new IllegalArgumentException("Duplicate declared Endpoint: " + key);
            }
        }
    }
    
    private static void validateRuntimeEndpointSnapshotItem(RuntimeEndpointSnapshot snapshot,
        AgentVersion selectedVersion, RuntimeEndpointSnapshotItem item,
        Set<EndpointNaturalKey> endpointKeys) {
        requireNonNull(item, "runtimeEndpointSnapshot item");
        validateEndpoint(item.getEndpoint());

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Reduce declaredEndpoints to 64 or fewer entries per CallInterface (the hard limit is enforced at AgentModelValidator.java:536).
2. If you need dynamic/large endpoint sets, move them to a runtime Endpoint snapshot (RuntimeEndpointSnapshot, cap 1000 items) instead of declared endpoints.
3. Split endpoints across multiple AgentCallInterface entries grouped by distinct protocol, since the limit applies per-protocol declared list, not per-Agent.
4. Verify your list builder is not duplicating entries; dedup first to free up slots.

Example fix

// before
callInterface.setDeclaredEndpoints(allRegistryInstances); // hundreds of entries
// after
callInterface.setDeclaredEndpoints(curatedStableEndpoints); // <= 64
snapshot.setItems(dynamicRuntimeEndpoints);            // runtime channel for fleet data

import com.alibaba.nacos.api.ai.utils.AgentModelValidator;
// before publish:
final int MAX = 64;
for (AgentCallInterface ci : agent.getCallInterfaces()) {
    List<Endpoint> eps = ci.getDeclaredEndpoints();
    if (eps != null && eps.size() > MAX) {
        throw new IllegalStateException("declaredEndpoints > 64 for protocol " + ci.getProtocol());
    }
}
AgentModelValidator.validateAgent(agent); // final server-side guard

// Java helper gate
static boolean declaredEndpointsWithinLimit(AgentCallInterface ci) {
    List<Endpoint> eps = ci.getDeclaredEndpoints();
    return eps == null || eps.size() <= 64;
}

try {
    AgentModelValidator.validateAgent(agent);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("declaredEndpoints exceeds")) {
        // split into runtime snapshot or trim the declared list
    } else throw e;
}

When it happens

Trigger: Publishing or updating an Agent whose AgentCallInterface.getDeclaredEndpoints() returns a list larger than 64 elements. Reached via AgentModelValidator.validateAgent / validateAgentSummary, which is called by the Agent publish/update API path (e.g. POST/PUT /v3/admin/ai/agent or /v3/console/ai/agent draft endpoints).

Common situations: Bulk-importing a service registry snapshot into declaredEndpoints by mistake (declared endpoints are meant for hand-curated stable addresses, not fleet data); copy-pasting a large endpoint pool from a discovery system into the Agent draft JSON; merging many per-region endpoint lists without dedup or splitting across protocols.

Related errors

• tags exceeds {MAX_TAGS} items
• extensions exceeds {MAX_EXTENSIONS} entries
• {fieldName} must contain 1 to {MAX_CALL_INTERFACES} values
• callInterfaces must contain 1 to {MAX_CALL_INTERFACES} items
• Duplicate declared Endpoint: {key}

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