alibaba/nacos · error · IllegalArgumentException

runtimeEndpointSnapshot.items exceeds {MAX_RUNTIME_ENDPOINTS

Error message

runtimeEndpointSnapshot.items exceeds {MAX_RUNTIME_ENDPOINTS} items

What it means

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.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java:291

     * Validate a raw runtime Endpoint management snapshot.
     *
     * @param snapshot runtime Endpoint snapshot
     * @throws IllegalArgumentException when the snapshot is invalid
     */
    public static void validateRuntimeEndpointSnapshot(RuntimeEndpointSnapshot snapshot) {
        requireNonNull(snapshot, "runtimeEndpointSnapshot");
        AgentValidationUtils.validateNamespaceId(snapshot.getNamespaceId());
        AgentValidationUtils.validateAgentName(snapshot.getAgentName());
        AgentValidationUtils.validateProtocol(snapshot.getProtocol());
        AgentVersion selectedVersion = null;
        if (snapshot.getVersion() != null) {
            selectedVersion = AgentVersion.parse(snapshot.getVersion());
        }
        
        List<RuntimeEndpointSnapshotItem> items = snapshot.getItems();
        requireNonNull(items, "runtimeEndpointSnapshot.items");
        if (items.size() > MAX_RUNTIME_ENDPOINTS) {
            throw new IllegalArgumentException(
                "runtimeEndpointSnapshot.items exceeds " + MAX_RUNTIME_ENDPOINTS + " items");
        }
        Set<EndpointNaturalKey> endpointKeys = new HashSet<EndpointNaturalKey>();
        for (RuntimeEndpointSnapshotItem item : items) {
            validateRuntimeEndpointSnapshotItem(snapshot, selectedVersion, item, endpointKeys);
        }
    }
    
    private static void validateAgentFields(String namespaceId, String agentName,
        String displayName, String description, String iconUrl, AgentProvider provider,
        List<String> tags, String status, String owner, String scope,
        AgentVersionInfo versionInfo, AgentVersionCatalog versionCatalog, Long metaVersion,
        Long createTime, Long updateTime) {
        AgentValidationUtils.validateNamespaceId(namespaceId);
        AgentValidationUtils.validateAgentName(agentName);
        validateOptionalLength(displayName, MAX_DISPLAY_NAME_LENGTH, "displayName");
        validateOptionalLength(description, MAX_DESCRIPTION_LENGTH, "description");
        if (iconUrl != null) {

View on GitHub (pinned to 9b989acdf1)

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.

Example fix

// before
RuntimeEndpointSnapshot snap = new RuntimeEndpointSnapshot();
snap.setItems(allEndpoints); // 1500 items
// set namespaceId, agentName, protocol ...
AgentModelValidator.validateRuntimeEndpointSnapshot(snap); // throws

// after
RuntimeEndpointSnapshot snap = new RuntimeEndpointSnapshot();
snap.setItems(allEndpoints.subList(0, 1000));
// set namespaceId, agentName, protocol ...
AgentModelValidator.validateRuntimeEndpointSnapshot(snap); // ok

Defensive patterns

Strategy: validation

Validate before calling

static final int MAX = 1000;
if (snapshot.getItems().size() > MAX) {
    snapshot.setItems(snapshot.getItems().subList(0, MAX));
}
AgentModelValidator.validateRuntimeEndpointSnapshot(snapshot);

Type guard

static boolean withinEndpointLimit(List<?> items) {
    return items != null && items.size() <= 1000;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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