{"record":{"id":"598e930acc5a25ef","repo":"alibaba/nacos","slug":"503","errorCode":"503","errorMessage":"Runtime Endpoint result exceeds 1000 natural keys","messagePattern":"Runtime Endpoint result exceeds 1000 natural keys","errorType":"exception","errorClass":"NacosException","httpStatus":503,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/runtime/AgentRuntimeRegistryService.java","lineNumber":356,"sourceCode":"        current.setBindings(new ArrayList<RuntimeVersionBinding>(bindings));\n        current.setEnabled(current.getEnabled() || contribution.getEnabled());\n        current.setHealthy(current.getHealthy() || contribution.getHealthy());\n        current.setState(runtimeState(current.getEnabled(), current.getHealthy()));\n    }\n    \n    private RuntimeEndpointState runtimeState(boolean enabled, boolean healthy) {\n        if (!enabled) {\n            return RuntimeEndpointState.DISABLED;\n        }\n        if (!healthy) {\n            return RuntimeEndpointState.UNHEALTHY;\n        }\n        return RuntimeEndpointState.AVAILABLE;\n    }\n    \n    private void validateCapacity(int size) throws NacosException {\n        if (size > MAX_RUNTIME_ENDPOINTS) {\n            throw new NacosException(NacosException.OVER_THRESHOLD,\n                \"Runtime Endpoint result exceeds \" + MAX_RUNTIME_ENDPOINTS\n                    + \" natural keys\");\n        }\n    }\n    \n    private Service composeService(String namespaceId, String agentName, String protocol) {\n        return Service.newService(namespaceId, Constants.Agent.AGENT_ENDPOINT_GROUP,\n            RadServiceNameComposer.compose(agentName, protocol));\n    }\n    \n    private void validateReadIdentity(String namespaceId, String agentName, String protocol,\n        String version) {\n        AgentValidationUtils.validateNamespaceId(namespaceId);\n        AgentValidationUtils.validateAgentName(agentName);\n        AgentValidationUtils.validateProtocol(protocol);\n        if (version != null) {\n            AgentValidationUtils.validateVersion(version);\n        }","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/runtime/AgentRuntimeRegistryService.java#L338-L374","documentation":"A single RAD discovery or snapshot query produced more than 1000 (MAX_RUNTIME_ENDPOINTS) distinct endpoint natural keys. The AgentRuntimeRegistryService.validateCapacity method (line 355) throws this NacosException (code OVER_THRESHOLD, effectively HTTP 503) to protect the server from unbounded response sizes. Natural keys are unique (namespaceId, agentName, protocol, endpoint URI/transport) combinations after deduplication.","triggerScenarios":"Calling getRuntimeEndpointSnapshot or getRuntimeEndpointSet for an agent/protocol whose registered instances collectively define more than 1000 unique endpoint natural keys. This can happen with many publishers each registering distinct endpoints.","commonSituations":"A large-scale Agent deployment with thousands of endpoint URIs; accidental endpoint proliferation from clients generating unique URIs per registration; a configuration error that registers every micro-instance as a separate endpoint instead of load-balancing behind fewer URIs.","solutions":["Reduce the number of distinct endpoint URIs for this agent/protocol to at most 1000 by consolidating behind load balancers or shared endpoints.","If the scale is legitimate, discuss raising MAX_RUNTIME_ENDPOINTS with maintainers — but consider the memory and response-size implications.","Partition endpoints across multiple agent names or protocols if the Agent serves diverse endpoint sets.","Audit registrations to detect and remove stale or duplicate endpoint URIs."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before registering, estimate the total unique endpoint count\nint estimatedKeys = batch.getEndpoints().stream()\n    .map(e -> EndpointNaturalKey.of(ns, name, proto, e))\n    .collect(Collectors.toSet()).size();\nif (estimatedKeys > 1000) {\n    throw new IllegalStateException(\"Endpoint batch would exceed 1000 natural keys\");\n}","typeGuard":"public static boolean isWithinCapacity(int naturalKeyCount) {\n    return naturalKeyCount <= 1000;\n}","tryCatchPattern":"try {\n    return registry.getRuntimeEndpointSet(ns, name, proto, versions);\n} catch (NacosException e) {\n    if (e.getErrCode() == NacosException.OVER_THRESHOLD) {\n        // return a capped/paginated result or advise the caller to narrow the query\n        logger.warn(\"Endpoint capacity exceeded for {}/{}/{}\", ns, name, proto);\n    }\n    throw e;\n}","preventionTips":["Consolidate endpoints behind shared URIs/load balancers instead of registering each instance separately.","Monitor the natural-key count per agent/protocol and alert before it approaches 1000.","Partition very large endpoint sets across multiple agent names or protocols."],"tags":["ai-agent","runtime-discovery","capacity-limit","scalability"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}