alibaba/nacos · error · IllegalArgumentException

Runtime EndpointSet Versions must not be empty

Error message

Runtime EndpointSet Versions must not be empty

What it means

Thrown by AgentRuntimeRegistryService.validateDiscoveryVersions when the versions list passed to getRuntimeEndpointSet(namespaceId, agentName, protocol, List<String> versions) is null or empty. RAD discovery requires at least one target Agent Version to resolve compatible runtime endpoints; an empty set means the caller has no version to discover against.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/runtime/AgentRuntimeRegistryService.java:381

        return Service.newService(namespaceId, Constants.Agent.AGENT_ENDPOINT_GROUP,
            RadServiceNameComposer.compose(agentName, protocol));
    }
    
    private void validateReadIdentity(String namespaceId, String agentName, String protocol,
        String version) {
        AgentValidationUtils.validateNamespaceId(namespaceId);
        AgentValidationUtils.validateAgentName(agentName);
        AgentValidationUtils.validateProtocol(protocol);
        if (version != null) {
            AgentValidationUtils.validateVersion(version);
        }
    }
    
    private void validateDiscoveryVersions(String namespaceId, String agentName, String protocol,
        List<String> versions) {
        validateReadIdentity(namespaceId, agentName, protocol, null);
        if (versions == null || versions.isEmpty()) {
            throw new IllegalArgumentException(
                "Runtime EndpointSet Versions must not be empty");
        }
        for (String version : versions) {
            AgentValidationUtils.validateVersion(version);
        }
    }
    
    private void sortRuntimeEndpoints(String namespaceId, String agentName, String protocol,
        List<AgentDiscoveryEndpoint> endpoints) {
        Collections.sort(endpoints, new Comparator<AgentDiscoveryEndpoint>() {
            
            @Override
            public int compare(AgentDiscoveryEndpoint left, AgentDiscoveryEndpoint right) {
                int result = Integer.compare(left.getPriority(), right.getPriority());
                if (result != 0) {
                    return result;
                }
                EndpointNaturalKey leftKey =

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Before calling getRuntimeEndpointSet, check that versions is non-null and non-empty; return an empty result or surface a 'no compatible version' error to the caller instead.
  2. If you have a single version, use the String overload getRuntimeEndpointSet(namespaceId, agentName, protocol, version) which rejects null but handles the singleton for you.
  3. Ensure the upstream version-catalog query that populates runtimeVersions returns at least one online version; investigate why no online versions exist for the agent/protocol.

Example fix

// before
EndpointSet set = registryService.getRuntimeEndpointSet(ns, agent, protocol, runtimeVersions);

// after
if (runtimeVersions == null || runtimeVersions.isEmpty()) {
    return EndpointSet.empty(EndpointSource.RUNTIME);
}
EndpointSet set = registryService.getRuntimeEndpointSet(ns, agent, protocol, runtimeVersions);
Defensive patterns

Strategy: validation

Validate before calling

if (versions == null || versions.isEmpty()) {
    throw new IllegalArgumentException(
        "At least one runtime version is required for discovery of " + agentName);
}
EndpointSet set = registryService.getRuntimeEndpointSet(namespaceId, agentName, protocol, versions);

Try / catch

try {
    EndpointSet set = registryService.getRuntimeEndpointSet(ns, agent, protocol, versions);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Versions must not be empty")) {
        // no compatible online version; return empty discovery result
        return EndpointSet.empty();
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling getRuntimeEndpointSet with a null or empty versions list; calling the single-version overload getRuntimeEndpointSet(..., String version) is safe (it wraps into a singleton list), but passing Collections.emptyList() or null directly to the List overload triggers this. Reachable via AgentDiscoveryApplicationService.resolveEndpointSets when runtimeVersions resolves to an empty list.

Common situations: A discovery client computes compatible online versions from a version catalog and the catalog query returns empty (no online versions), then forwards that empty list to discovery. Also happens when a caller mistakenly passes the result of a filtered stream that yielded no elements without checking.

Related errors

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