{"record":{"id":"7c856f26fc634308","repo":"alibaba/nacos","slug":"runtimeendpointsnapshot-items-exceeds-max-runtime","errorCode":null,"errorMessage":"runtimeEndpointSnapshot.items exceeds {MAX_RUNTIME_ENDPOINTS} items","messagePattern":"runtimeEndpointSnapshot\\.items exceeds (.+?) items","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":291,"sourceCode":"     * Validate a raw runtime Endpoint management snapshot.\n     *\n     * @param snapshot runtime Endpoint snapshot\n     * @throws IllegalArgumentException when the snapshot is invalid\n     */\n    public static void validateRuntimeEndpointSnapshot(RuntimeEndpointSnapshot snapshot) {\n        requireNonNull(snapshot, \"runtimeEndpointSnapshot\");\n        AgentValidationUtils.validateNamespaceId(snapshot.getNamespaceId());\n        AgentValidationUtils.validateAgentName(snapshot.getAgentName());\n        AgentValidationUtils.validateProtocol(snapshot.getProtocol());\n        AgentVersion selectedVersion = null;\n        if (snapshot.getVersion() != null) {\n            selectedVersion = AgentVersion.parse(snapshot.getVersion());\n        }\n        \n        List<RuntimeEndpointSnapshotItem> items = snapshot.getItems();\n        requireNonNull(items, \"runtimeEndpointSnapshot.items\");\n        if (items.size() > MAX_RUNTIME_ENDPOINTS) {\n            throw new IllegalArgumentException(\n                \"runtimeEndpointSnapshot.items exceeds \" + MAX_RUNTIME_ENDPOINTS + \" items\");\n        }\n        Set<EndpointNaturalKey> endpointKeys = new HashSet<EndpointNaturalKey>();\n        for (RuntimeEndpointSnapshotItem item : items) {\n            validateRuntimeEndpointSnapshotItem(snapshot, selectedVersion, item, endpointKeys);\n        }\n    }\n    \n    private static void validateAgentFields(String namespaceId, String agentName,\n        String displayName, String description, String iconUrl, AgentProvider provider,\n        List<String> tags, String status, String owner, String scope,\n        AgentVersionInfo versionInfo, AgentVersionCatalog versionCatalog, Long metaVersion,\n        Long createTime, Long updateTime) {\n        AgentValidationUtils.validateNamespaceId(namespaceId);\n        AgentValidationUtils.validateAgentName(agentName);\n        validateOptionalLength(displayName, MAX_DISPLAY_NAME_LENGTH, \"displayName\");\n        validateOptionalLength(description, MAX_DESCRIPTION_LENGTH, \"description\");\n        if (iconUrl != null) {","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L273-L309","documentation":"Thrown by AgentModelValidator.validateRuntimeEndpointSnapshot as an IllegalArgumentException when snapshot.getItems() contains more than MAX_RUNTIME_ENDPOINTS (1000) entries. This caps the size of a runtime endpoint snapshot to keep discovery payloads bounded.","triggerScenarios":"Calling validateRuntimeEndpointSnapshot with a snapshot whose items list size exceeds 1000. Occurs when a runtime endpoint source returned a very large set of endpoints in one snapshot.","commonSituations":"A service registry backing the agent has thousands of instances and the snapshot collected all of them; the endpoint source did not paginate or filter; a test loaded an oversized fixture.","solutions":["Limit or shard the snapshot to at most 1000 endpoints per payload.","Filter endpoints by health/zone/version to reduce the count below the cap.","If more endpoints are needed, split into multiple snapshots by protocol or partition."],"exampleFix":"// before\nRuntimeEndpointSnapshot snap = new RuntimeEndpointSnapshot();\nsnap.setItems(allEndpoints); // 1500 items\n// set namespaceId, agentName, protocol ...\nAgentModelValidator.validateRuntimeEndpointSnapshot(snap); // throws\n\n// after\nRuntimeEndpointSnapshot snap = new RuntimeEndpointSnapshot();\nsnap.setItems(allEndpoints.subList(0, 1000));\n// set namespaceId, agentName, protocol ...\nAgentModelValidator.validateRuntimeEndpointSnapshot(snap); // ok","handlingStrategy":"validation","validationCode":"static final int MAX = 1000;\nif (snapshot.getItems().size() > MAX) {\n    snapshot.setItems(snapshot.getItems().subList(0, MAX));\n}\nAgentModelValidator.validateRuntimeEndpointSnapshot(snapshot);","typeGuard":"static boolean withinEndpointLimit(List<?> items) {\n    return items != null && items.size() <= 1000;\n}","tryCatchPattern":null,"preventionTips":["Cap endpoint discovery results at 1000 per snapshot.","Shard large endpoint sets by protocol, zone, or partition.","Filter unhealthy endpoints to reduce volume before validation."],"tags":["java","nacos","ai","agents","validation","capacity","endpoints"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}