alibaba/nacos · error · UnsupportedOperationException

Do not support persistent instances to perform batch registr

Error message

Do not support persistent instances to perform batch registration methods.

What it means

Thrown unconditionally by NamingHttpClientProxy.batchRegisterService (UnsupportedOperationException). Batch registration is not implemented for the HTTP naming proxy — it only exists on the gRPC proxy. The message references persistent instances because the HTTP proxy is the persistent-instance path.

Source

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

        final Map<String, String> params = new HashMap<>(32);
        params.put(CommonParams.NAMESPACE_ID, namespaceId);
        params.put(CommonParams.SERVICE_NAME, groupedServiceName);
        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(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;

View on GitHub (pinned to 9b989acdf1)

Solutions

Use the gRPC naming client proxy — batch registration requires gRPC.
If stuck on HTTP, register instances individually with registerService and setEphemeral(false).
Ensure the Nacos client version is 2.x+ and gRPC is the active transport.

Example fix

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

// after — register individually over HTTP with persistent instances
for (Instance inst : instances) {
    inst.setEphemeral(false);
    namingService.registerInstance(serviceName, groupName, inst);
}

Defensive patterns

Strategy: fallback

Validate before calling

// Check transport before using batch APIs
if (isHttpTransport(namingService)) {
    // fall back to individual register
    for (Instance inst : instances) {
        inst.setEphemeral(false);
        namingService.registerInstance(serviceName, groupName, inst);
    }
} else {
    namingService.batchRegisterService(serviceName, groupName, instances);
}

Try / catch

try {
    namingService.batchRegisterService(serviceName, groupName, instances);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("batch registration")) {
        // HTTP proxy — fall back to individual registration
        for (Instance inst : instances) {
            inst.setEphemeral(false);
            namingService.registerInstance(serviceName, groupName, inst);
        }
    } else {
        throw e;
    }
}

Prevention

Use the gRPC transport if batch registration is required.
Maintain a fallback path that registers instances individually if the transport does not support batch.
Check the Nacos client version — batch registration requires 2.x+ with gRPC.

When it happens

Trigger: Calling batchRegisterService on a NamingService that is backed by the HTTP client proxy. This happens when the client is explicitly configured for HTTP or when only persistent instances are expected.

Common situations: Application calls batchRegisterService but the NamingService was created with HTTP transport; code copied from a gRPC example into an HTTP-configured deployment.

Related errors

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