{"record":{"id":"d0fb9f0c75db2f1e","repo":"alibaba/nacos","slug":"runtime-endpointset-version-must-not-be-null","errorCode":null,"errorMessage":"Runtime EndpointSet Version must not be null","messagePattern":"Runtime EndpointSet Version must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/runtime/AgentRuntimeRegistryService.java","lineNumber":174,"sourceCode":"        result.setItems(loadSnapshotItems(namespaceId, agentName, protocol, version));\n        AgentModelValidator.validateRuntimeEndpointSnapshot(result);\n        return result;\n    }\n    \n    /**\n     * Return enabled Runtime Endpoints for RAD discovery.\n     *\n     * @param namespaceId namespace identifier\n     * @param agentName Agent name\n     * @param protocol Agent protocol\n     * @param version exact target Agent Version\n     * @return Runtime Endpoint set and deterministic source revision\n     * @throws NacosException when Naming state cannot be represented by the Agent contract\n     */\n    public EndpointSet getRuntimeEndpointSet(String namespaceId, String agentName,\n        String protocol, String version) throws NacosException {\n        if (version == null) {\n            throw new IllegalArgumentException(\"Runtime EndpointSet Version must not be null\");\n        }\n        return getRuntimeEndpointSet(namespaceId, agentName, protocol,\n            Collections.singletonList(version));\n    }\n    \n    /**\n     * Return enabled Runtime Endpoints compatible with any supplied online Agent Version.\n     *\n     * @param namespaceId namespace identifier\n     * @param agentName Agent name\n     * @param protocol Agent protocol\n     * @param versions non-empty compatibility target Versions\n     * @return Runtime Endpoint set and deterministic source revision\n     * @throws NacosException when Naming state cannot be represented by the Agent contract\n     */\n    public EndpointSet getRuntimeEndpointSet(String namespaceId, String agentName,\n        String protocol, List<String> versions) throws NacosException {\n        validateDiscoveryVersions(namespaceId, agentName, protocol, versions);","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/runtime/AgentRuntimeRegistryService.java#L156-L192","documentation":"The single-version overload of getRuntimeEndpointSet requires a non-null version parameter. The AgentRuntimeRegistryService.getRuntimeEndpointSet(namespaceId, agentName, protocol, version) method (line 173) throws this IllegalArgumentException when version is null, because RAD discovery must target a concrete Agent Version. Callers needing version-agnostic discovery should use the multi-version overload instead.","triggerScenarios":"Calling agentRuntimeRegistryService.getRuntimeEndpointSet(ns, name, proto, null) — the single-version RAD discovery API with a null version. This is an internal service call, typically from a controller or gRPC handler that failed to resolve a version from the request.","commonSituations":"A discovery request that omitted the version parameter; a client that expects the server to pick a default version; a routing bug where null was not guarded before reaching this method.","solutions":["Pass a concrete non-null version string to getRuntimeEndpointSet.","If version-agnostic discovery is needed, call the multi-version overload getRuntimeEndpointSet(ns, name, proto, versions) with a non-empty list.","Resolve a default version (e.g. the catalog's latestVersion) before calling this method."],"exampleFix":"// before\nendpointSet = registry.getRuntimeEndpointSet(ns, name, proto, null);\n// after\nString version = resolveVersionFromRequest(request); // never null\nendpointSet = registry.getRuntimeEndpointSet(ns, name, proto, version);","handlingStrategy":"validation","validationCode":"if (version == null) {\n    version = catalog.getLatestVersion(); // resolve a default\n}\nif (version == null) {\n    throw new IllegalArgumentException(\"Cannot resolve a target Version for discovery\");\n}","typeGuard":"public static boolean isDiscoveryVersionValid(String version) {\n    return version != null && !version.isBlank();\n}","tryCatchPattern":"try {\n    registry.getRuntimeEndpointSet(ns, name, proto, version);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Version must not be null\")) {\n        version = resolveLatestVersion(ns, name, proto);\n    }\n}","preventionTips":["Always resolve a concrete version before calling the single-version overload.","If version-agnostic discovery is needed, use the multi-version overload with a non-empty list.","Validate version is non-null at the controller/handler boundary before reaching the service."],"tags":["ai-agent","runtime-discovery","validation","rad"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}