alibaba/nacos · error · UnsupportedOperationException

Do not support subscribe service by UDP, please use gRPC rep

Error message

Do not support subscribe service by UDP, please use gRPC replaced.

What it means

Thrown by NamingHttpClientProxy.subscribe (UnsupportedOperationException). Service subscription (push-based change notifications) over UDP/HTTP is not supported — the HTTP proxy provides no real-time subscription channel. Subscriptions require the gRPC proxy, which maintains a persistent stream.

Source

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

        String result = reqApi(UtilAndComs.nacosUrlBase + "/service/list", params, HttpMethod.GET);
        
        Map<String, Object> json =
            JsonUtils.toObj(result, new NacosTypeReference<Map<String, Object>>() {
            });
        ListView<String> listView = new ListView<>();
        Object count = json.get("count");
        listView.setCount(count instanceof Number ? ((Number) count).intValue() : 0);
        listView.setData(JsonUtils.toObj(JsonUtils.toJson(json.get("doms")),
            new NacosTypeReference<List<String>>() {
            }));
        
        return listView;
    }
    
    @Override
    public ServiceInfo subscribe(String serviceName, String groupName, String clusters)
        throws NacosException {
        throw new UnsupportedOperationException(
            "Do not support subscribe service by UDP, please use gRPC replaced.");
    }
    
    @Override
    public void unsubscribe(String serviceName, String groupName, String clusters)
        throws NacosException {
    }
    
    @Override
    public boolean isSubscribed(String serviceName, String groupName, String clusters)
        throws NacosException {
        return true;
    }
    
    public String reqApi(String api, Map<String, String> params, String method)
        throws NacosException {
        return reqApi(api, params, Collections.EMPTY_MAP, method);
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

Switch to the gRPC naming client proxy — subscriptions require the gRPC push channel.
If HTTP is mandatory, poll getAllInstances periodically as a fallback (with the cost of latency).
Ensure the client configuration enables gRPC as the transport for naming.

Defensive patterns

Strategy: fallback

Validate before calling

// For HTTP transport, use polling instead of subscribe
if (isHttpTransport(namingService)) {
    // poll getAllInstances periodically
    ScheduledExecutorService scheduler = ...;
    scheduler.scheduleAtFixedRate(() -> {
        List<Instance> instances = namingService.getAllInstances(serviceName);
        // process changes
    }, 0, 5, TimeUnit.SECONDS);
} else {
    namingService.subscribe(serviceName, eventListener);
}

Try / catch

try {
    namingService.subscribe(serviceName, groupName, clusters, eventListener);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("subscribe service by UDP")) {
        // fall back to polling
        startPollingFallback(serviceName, groupName, clusters);
    } else {
        throw e;
    }
}

Prevention

Use gRPC transport for service subscriptions.
For HTTP-only deployments, implement a polling fallback with an appropriate interval.
Document that real-time push notifications require gRPC.

When it happens

Trigger: Calling NamingService.subscribe or equivalent on a NamingService backed by the HTTP client proxy. The HTTP proxy's subscribe method is a stub that always throws.

Common situations: Application relies on event-driven service change notifications but is configured with HTTP transport; legacy code that assumes subscription works over HTTP.

Related errors

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