alibaba/nacos · error · IllegalArgumentException

declaredEndpoints exceeds

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.

Solutions

Reduce declaredEndpoints to 64 or fewer entries per CallInterface (the hard limit is enforced at AgentModelValidator.java:536).
If you need dynamic/large endpoint sets, move them to a runtime Endpoint snapshot (RuntimeEndpointSnapshot, cap 1000 items) instead of declared endpoints.
Split endpoints across multiple AgentCallInterface entries grouped by distinct protocol, since the limit applies per-protocol declared list, not per-Agent.
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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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;
}

Prevention

Treat declaredEndpoints as hand-curated config (<=64), not a fleet registry.
Use RuntimeEndpointSnapshot (cap 1000) for dynamic/large endpoint sets.
Dedup declared endpoints before counting them.

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

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

Appendix: 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)