alibaba/nacos · error · UnsupportedOperationException

Do not support query instance by http client,please use gRPC

Error message

Do not support query instance by http client,please use gRPC replaced.

What it means

Thrown by NamingHttpClientProxy.queryInstancesOfService (UnsupportedOperationException). Querying the full instance list of a service (with cluster and healthyOnly filters) is not implemented for the HTTP naming proxy — it requires gRPC.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/naming/remote/http/NamingHttpClientProxy.java:219

        params.put(CommonParams.NAMESPACE_ID, namespaceId);
        params.put(CommonParams.SERVICE_NAME, serviceName);
        params.put(CommonParams.GROUP_NAME, groupName);
        params.put(CommonParams.CLUSTER_NAME, instance.getClusterName());
        params.put(IP_PARAM, instance.getIp());
        params.put(PORT_PARAM, String.valueOf(instance.getPort()));
        params.put(WEIGHT_PARAM, String.valueOf(instance.getWeight()));
        params.put(ENABLE_PARAM, String.valueOf(instance.isEnabled()));
        params.put(EPHEMERAL_PARAM, String.valueOf(instance.isEphemeral()));
        params.put(META_PARAM, JsonUtils.toJson(instance.getMetadata()));
        
        reqApi(UtilAndComs.nacosUrlInstance, params, HttpMethod.PUT);
    }
    
    @Override
    public ServiceInfo queryInstancesOfService(String serviceName, String groupName,
        String clusters,
        boolean healthyOnly) {
        throw new UnsupportedOperationException(
            "Do not support query instance by http client,please use gRPC replaced.");
    }
    
    @Override
    public Service queryService(String serviceName, String groupName) throws NacosException {
        NAMING_LOGGER.info("[QUERY-SERVICE] {} query service : {}, {}", namespaceId, serviceName,
            groupName);
        
        final Map<String, String> params = new HashMap<>(16);
        params.put(CommonParams.NAMESPACE_ID, namespaceId);
        params.put(CommonParams.SERVICE_NAME, serviceName);
        params.put(CommonParams.GROUP_NAME, groupName);
        
        String result = reqApi(UtilAndComs.nacosUrlService, params, HttpMethod.GET);
        return JsonUtils.toObj(result, Service.class);
    }
    
    @Override

View on GitHub (pinned to 9b989acdf1)

Solutions

Use the gRPC naming client proxy for instance list queries.
If HTTP is required, use selectInstances or getAllInstances which may have HTTP support, depending on version.
Confirm the transport is gRPC in the NamingService factory configuration.

Defensive patterns

Strategy: fallback

Validate before calling

// Use getAllInstances as an alternative for HTTP transport
if (isHttpTransport(namingService)) {
    List<Instance> all = namingService.getAllInstances(serviceName, groupName, clusters);
    // filter healthyOnly manually
} else {
    ServiceInfo info = namingServiceProxy.queryInstancesOfService(serviceName, groupName, clusters, healthyOnly);
}

Try / catch

try {
    ServiceInfo info = namingServiceProxy.queryInstancesOfService(serviceName, groupName, clusters, healthyOnly);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("query instance by http")) {
        List<Instance> all = namingService.getAllInstances(serviceName, groupName, clusters);
        // apply healthyOnly filter manually
    } else {
        throw e;
    }
}

Prevention

Use the gRPC transport for queryInstancesOfService.
For HTTP deployments, use getAllInstances and filter client-side.
Document which query APIs are available per transport.

When it happens

Trigger: Calling queryInstancesOfService on a NamingService backed by the HTTP client proxy. This is a less commonly used API that the HTTP proxy deliberately omits.

Common situations: Application uses queryInstancesOfService and the NamingService was created with HTTP transport; migrating from gRPC to HTTP without checking API compatibility.

Related errors

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