alibaba/nacos · error · IllegalArgumentException

Runtime EndpointSet Version must not be null

Error message

Runtime EndpointSet Version must not be null

What it means

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.

Source

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

        result.setItems(loadSnapshotItems(namespaceId, agentName, protocol, version));
        AgentModelValidator.validateRuntimeEndpointSnapshot(result);
        return result;
    }
    
    /**
     * Return enabled Runtime Endpoints for RAD discovery.
     *
     * @param namespaceId namespace identifier
     * @param agentName Agent name
     * @param protocol Agent protocol
     * @param version exact target Agent Version
     * @return Runtime Endpoint set and deterministic source revision
     * @throws NacosException when Naming state cannot be represented by the Agent contract
     */
    public EndpointSet getRuntimeEndpointSet(String namespaceId, String agentName,
        String protocol, String version) throws NacosException {
        if (version == null) {
            throw new IllegalArgumentException("Runtime EndpointSet Version must not be null");
        }
        return getRuntimeEndpointSet(namespaceId, agentName, protocol,
            Collections.singletonList(version));
    }
    
    /**
     * Return enabled Runtime Endpoints compatible with any supplied online Agent Version.
     *
     * @param namespaceId namespace identifier
     * @param agentName Agent name
     * @param protocol Agent protocol
     * @param versions non-empty compatibility target Versions
     * @return Runtime Endpoint set and deterministic source revision
     * @throws NacosException when Naming state cannot be represented by the Agent contract
     */
    public EndpointSet getRuntimeEndpointSet(String namespaceId, String agentName,
        String protocol, List<String> versions) throws NacosException {
        validateDiscoveryVersions(namespaceId, agentName, protocol, versions);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass a concrete non-null version string to getRuntimeEndpointSet.
2. If version-agnostic discovery is needed, call the multi-version overload getRuntimeEndpointSet(ns, name, proto, versions) with a non-empty list.
3. Resolve a default version (e.g. the catalog's latestVersion) before calling this method.

Example fix

// before
endpointSet = registry.getRuntimeEndpointSet(ns, name, proto, null);
// after
String version = resolveVersionFromRequest(request); // never null
endpointSet = registry.getRuntimeEndpointSet(ns, name, proto, version);

if (version == null) {
    version = catalog.getLatestVersion(); // resolve a default
}
if (version == null) {
    throw new IllegalArgumentException("Cannot resolve a target Version for discovery");
}

public static boolean isDiscoveryVersionValid(String version) {
    return version != null && !version.isBlank();
}

try {
    registry.getRuntimeEndpointSet(ns, name, proto, version);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Version must not be null")) {
        version = resolveLatestVersion(ns, name, proto);
    }
}

When it happens

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

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

Related errors

• 10000
• 20002
• 10000
• 20002
• 20002

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