alibaba/nacos · error · UnsupportedOperationException

Do not support persistent instances to perform batch de regi

Error message

Do not support persistent instances to perform batch de registration methods.

What it means

Thrown unconditionally by NamingHttpClientProxy.batchDeregisterService (UnsupportedOperationException). Batch deregistration, like batch registration, is only available on the gRPC naming client proxy.

Source

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

        params.put(WEIGHT_PARAM, String.valueOf(instance.getWeight()));
        params.put(REGISTER_ENABLE_PARAM, String.valueOf(instance.isEnabled()));
        params.put(HEALTHY_PARAM, String.valueOf(instance.isHealthy()));
        params.put(EPHEMERAL_PARAM, String.valueOf(instance.isEphemeral()));
        params.put(META_PARAM, JsonUtils.toJson(instance.getMetadata()));
        reqApi(UtilAndComs.nacosUrlInstance, params, HttpMethod.POST);
    }
    
    @Override
    public void batchRegisterService(String serviceName, String groupName,
        List<Instance> instances) {
        throw new UnsupportedOperationException(
            "Do not support persistent instances to perform batch registration methods.");
    }
    
    @Override
    public void batchDeregisterService(String serviceName, String groupName,
        List<Instance> instances) {
        throw new UnsupportedOperationException(
            "Do not support persistent instances to perform batch de registration methods.");
    }
    
    @Override
    public void deregisterService(String serviceName, String groupName, Instance instance)
        throws NacosException {
        NAMING_LOGGER.info("[DEREGISTER-SERVICE] {} deregistering service {} with instance: {}",
            namespaceId,
            serviceName, instance);
        if (instance.isEphemeral()) {
            return;
        }
        final Map<String, String> params = new HashMap<>(16);
        params.put(CommonParams.NAMESPACE_ID, namespaceId);
        params.put(CommonParams.SERVICE_NAME, NamingUtils.getGroupedName(serviceName, groupName));
        params.put(CommonParams.CLUSTER_NAME, instance.getClusterName());
        params.put(IP_PARAM, instance.getIp());
        params.put(PORT_PARAM, String.valueOf(instance.getPort()));

View on GitHub (pinned to 9b989acdf1)

Solutions

Switch to the gRPC naming client proxy to use batch deregistration.
If HTTP is required, deregister instances individually with deregisterService.
Verify the client transport configuration to ensure gRPC is active.

Example fix

// before — HTTP proxy does not support batch deregister
namingService.batchDeregisterService(serviceName, groupName, instances);

// after — deregister individually over HTTP
for (Instance inst : instances) {
    namingService.deregisterInstance(serviceName, groupName, inst);
}

Defensive patterns

Strategy: fallback

Validate before calling

if (isHttpTransport(namingService)) {
    for (Instance inst : instances) {
        namingService.deregisterInstance(serviceName, groupName, inst);
    }
} else {
    namingService.batchDeregisterService(serviceName, groupName, instances);
}

Try / catch

try {
    namingService.batchDeregisterService(serviceName, groupName, instances);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("batch de registration")) {
        for (Instance inst : instances) {
            namingService.deregisterInstance(serviceName, groupName, inst);
        }
    } else {
        throw e;
    }
}

Prevention

Use gRPC transport for batch deregistration.
Implement an individual-deregister fallback for HTTP deployments.
Verify transport compatibility before calling batch APIs.

When it happens

Trigger: Calling batchDeregisterService on a NamingService backed by the HTTP client proxy.

Common situations: Same as batch registration: HTTP-configured client or code ported from a gRPC deployment without adjusting transport.

Related errors

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