{"record":{"id":"5948984aa1b10f09","repo":"alibaba/nacos","slug":"declaredendpoints-exceeds-max-declared-endpoints","errorCode":null,"errorMessage":"declaredEndpoints exceeds {MAX_DECLARED_ENDPOINTS} items","messagePattern":"declaredEndpoints exceeds (.+?) items","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":537,"sourceCode":"        if (sourceOrder.isEmpty() || sourceOrder.size() > EndpointSource.values().length) {\n            throw new IllegalArgumentException(\"endpointSourceOrder must contain 1 or 2 sources\");\n        }\n        Set<EndpointSource> uniqueSources = new HashSet<EndpointSource>();\n        for (EndpointSource source : sourceOrder) {\n            requireNonNull(source, \"endpointSourceOrder item\");\n            if (!uniqueSources.add(source)) {\n                throw new IllegalArgumentException(\"Duplicate Endpoint source: \" + source);\n            }\n        }\n    }\n    \n    private static void validateDeclaredEndpoints(String namespaceId, String agentName,\n        String protocol, List<Endpoint> endpoints) {\n        if (endpoints == null) {\n            return;\n        }\n        if (endpoints.size() > MAX_DECLARED_ENDPOINTS) {\n            throw new IllegalArgumentException(\n                \"declaredEndpoints exceeds \" + MAX_DECLARED_ENDPOINTS + \" items\");\n        }\n        Set<EndpointNaturalKey> endpointKeys = new HashSet<EndpointNaturalKey>();\n        for (Endpoint endpoint : endpoints) {\n            validateEndpoint(endpoint);\n            EndpointNaturalKey key = EndpointNaturalKey.of(namespaceId, agentName, protocol,\n                endpoint);\n            if (!endpointKeys.add(key)) {\n                throw new IllegalArgumentException(\"Duplicate declared Endpoint: \" + key);\n            }\n        }\n    }\n    \n    private static void validateRuntimeEndpointSnapshotItem(RuntimeEndpointSnapshot snapshot,\n        AgentVersion selectedVersion, RuntimeEndpointSnapshotItem item,\n        Set<EndpointNaturalKey> endpointKeys) {\n        requireNonNull(item, \"runtimeEndpointSnapshot item\");\n        validateEndpoint(item.getEndpoint());","sourceCodeStart":519,"sourceCodeEnd":555,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L519-L555","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\ncallInterface.setDeclaredEndpoints(allRegistryInstances); // hundreds of entries\n// after\ncallInterface.setDeclaredEndpoints(curatedStableEndpoints); // <= 64\nsnapshot.setItems(dynamicRuntimeEndpoints);            // runtime channel for fleet data","handlingStrategy":"validation","validationCode":"import com.alibaba.nacos.api.ai.utils.AgentModelValidator;\n// before publish:\nfinal int MAX = 64;\nfor (AgentCallInterface ci : agent.getCallInterfaces()) {\n    List<Endpoint> eps = ci.getDeclaredEndpoints();\n    if (eps != null && eps.size() > MAX) {\n        throw new IllegalStateException(\"declaredEndpoints > 64 for protocol \" + ci.getProtocol());\n    }\n}\nAgentModelValidator.validateAgent(agent); // final server-side guard","typeGuard":"// Java helper gate\nstatic boolean declaredEndpointsWithinLimit(AgentCallInterface ci) {\n    List<Endpoint> eps = ci.getDeclaredEndpoints();\n    return eps == null || eps.size() <= 64;\n}","tryCatchPattern":"try {\n    AgentModelValidator.validateAgent(agent);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"declaredEndpoints exceeds\")) {\n        // split into runtime snapshot or trim the declared list\n    } else throw e;\n}","preventionTips":["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."],"tags":["ai-agent","validation","capacity-limit","endpoints"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}