alibaba/nacos · error · IllegalArgumentException

Runtime Endpoint projection exceeds 1000 items

Error message

Runtime Endpoint projection exceeds 1000 items

What it means

The RuntimeEndpointRevision computer caps a single runtime Endpoint projection at 1000 endpoints (MAX_ENDPOINTS). This guard in revisionBytes runs before canonicalization and hashing, preventing unbounded projections from consuming excessive memory and CPU during revision computation.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/fingerprint/RuntimeEndpointRevision.java:88

        List<AgentDiscoveryEndpoint> endpoints) {
        byte[] revisionBytes = revisionBytes(namespaceId, agentName, protocol, endpoints);
        long[] hash = MurmurHash3.hash128x64(revisionBytes, 0, revisionBytes.length, MURMUR_SEED);
        char[] value = new char[32];
        appendHex(hash[0], value, 0);
        appendHex(hash[1], value, 16);
        return TOKEN_PREFIX + new String(value);
    }
    
    static byte[] revisionBytes(String namespaceId, String agentName, String protocol,
        List<AgentDiscoveryEndpoint> endpoints) {
        AgentValidationUtils.validateNamespaceId(namespaceId);
        AgentValidationUtils.validateAgentName(agentName);
        AgentValidationUtils.validateProtocol(protocol);
        if (endpoints == null) {
            throw new IllegalArgumentException("Runtime Endpoint projection must not be null");
        }
        if (endpoints.size() > MAX_ENDPOINTS) {
            throw new IllegalArgumentException(
                "Runtime Endpoint projection exceeds " + MAX_ENDPOINTS + " items");
        }
        Map<EndpointNaturalKey, AgentDiscoveryEndpoint> canonicalEndpoints =
            new TreeMap<EndpointNaturalKey, AgentDiscoveryEndpoint>();
        for (AgentDiscoveryEndpoint endpoint : endpoints) {
            Endpoint canonicalEndpoint = EndpointCanonicalizer.canonicalize(endpoint);
            AgentDiscoveryEndpoint canonical = copyEndpoint(canonicalEndpoint);
            if (canonical.getHealthy() == null) {
                throw new IllegalArgumentException("Runtime Endpoint healthy must not be null");
            }
            canonical.setBindings(canonicalBindings(endpoint.getBindings()));
            EndpointNaturalKey key = EndpointNaturalKey.of(namespaceId, agentName, protocol,
                canonical);
            if (canonicalEndpoints.put(key, canonical) != null) {
                throw new IllegalArgumentException("Duplicate Runtime Endpoint: " + key);
            }
        }
        return frame(canonicalEndpoints);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Reduce the endpoint count to 1000 or fewer per protocol group by sharding across multiple Agents or protocol tokens.
2. Filter endpoints to include only healthy/enabled instances before submitting.
3. Paginate or batch endpoint registration across multiple revision computations.

Example fix

// before
List<AgentDiscoveryEndpoint> all = findAllEndpoints(); // 5000 items
String rev = RuntimeEndpointRevision.compute(ns, name, proto, all); // throws

// after — shard or filter
List<AgentDiscoveryEndpoint> batch = all.stream()
    .filter(AgentDiscoveryEndpoint::getHealthy)
    .limit(1000)
    .collect(Collectors.toList());
String rev = RuntimeEndpointRevision.compute(ns, name, proto, batch);

if (endpoints != null && endpoints.size() > 1000) {
    throw new IllegalArgumentException("Endpoint projection exceeds 1000 items: " + endpoints.size());
}

boolean withinEndpointLimit(List<?> endpoints) {
    return endpoints == null || endpoints.size() <= 1000;
}

When it happens

Trigger: Calling RuntimeEndpointRevision.compute(namespaceId, agentName, protocol, endpoints) where endpoints.size() > 1000. This happens during RAD protocol runtime endpoint registration or heartbeat when an Agent reports more than 1000 endpoints in one protocol group.

Common situations: A large-scale deployment registers hundreds of runtime instances under one Agent. A misconfigured auto-scaling group floods the registry with endpoint registrations. A test or load generator submits unbounded endpoint lists.

Related errors

• Runtime Endpoint healthy must not be null
• Duplicate Runtime Endpoint: {}
• Runtime Endpoint bindings must not be empty
• Runtime Endpoint binding must be complete
• Agent tags exceeds %s persisted characters

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