{"record":{"id":"a50ee21a882c45e9","repo":"alibaba/nacos","slug":"runtime-endpointset-versions-must-not-be-empty","errorCode":null,"errorMessage":"Runtime EndpointSet Versions must not be empty","messagePattern":"Runtime EndpointSet Versions must not be empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/runtime/AgentRuntimeRegistryService.java","lineNumber":381,"sourceCode":"        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        }\n    }\n    \n    private void validateDiscoveryVersions(String namespaceId, String agentName, String protocol,\n        List<String> versions) {\n        validateReadIdentity(namespaceId, agentName, protocol, null);\n        if (versions == null || versions.isEmpty()) {\n            throw new IllegalArgumentException(\n                \"Runtime EndpointSet Versions must not be empty\");\n        }\n        for (String version : versions) {\n            AgentValidationUtils.validateVersion(version);\n        }\n    }\n    \n    private void sortRuntimeEndpoints(String namespaceId, String agentName, String protocol,\n        List<AgentDiscoveryEndpoint> endpoints) {\n        Collections.sort(endpoints, new Comparator<AgentDiscoveryEndpoint>() {\n            \n            @Override\n            public int compare(AgentDiscoveryEndpoint left, AgentDiscoveryEndpoint right) {\n                int result = Integer.compare(left.getPriority(), right.getPriority());\n                if (result != 0) {\n                    return result;\n                }\n                EndpointNaturalKey leftKey =","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/runtime/AgentRuntimeRegistryService.java#L363-L399","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If you have a single version, use the String overload getRuntimeEndpointSet(namespaceId, agentName, protocol, version) which rejects null but handles the singleton for you.","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."],"exampleFix":"// before\nEndpointSet set = registryService.getRuntimeEndpointSet(ns, agent, protocol, runtimeVersions);\n\n// after\nif (runtimeVersions == null || runtimeVersions.isEmpty()) {\n    return EndpointSet.empty(EndpointSource.RUNTIME);\n}\nEndpointSet set = registryService.getRuntimeEndpointSet(ns, agent, protocol, runtimeVersions);","handlingStrategy":"validation","validationCode":"if (versions == null || versions.isEmpty()) {\n    throw new IllegalArgumentException(\n        \"At least one runtime version is required for discovery of \" + agentName);\n}\nEndpointSet set = registryService.getRuntimeEndpointSet(namespaceId, agentName, protocol, versions);","typeGuard":null,"tryCatchPattern":"try {\n    EndpointSet set = registryService.getRuntimeEndpointSet(ns, agent, protocol, versions);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Versions must not be empty\")) {\n        // no compatible online version; return empty discovery result\n        return EndpointSet.empty();\n    }\n    throw e;\n}","preventionTips":["Always derive runtimeVersions from a non-empty online version catalog query.","Prefer the single-version String overload when discovering exactly one version.","Unit-test the discovery path with an empty online-versions catalog."],"tags":["validation","agent-runtime","rad-discovery","illegal-argument"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}