alibaba/nacos · error · UnsupportedOperationException

Do not support register ephemeral instances by HTTP, please

Error message

Do not support register ephemeral instances by HTTP, please use gRPC replaced.

What it means

Thrown by NamingHttpClientProxy.registerService when the Instance has isEphemeral() == true (UnsupportedOperationException). The HTTP naming proxy only supports persistent (non-ephemeral) instance registration; ephemeral instances require the gRPC client proxy.

Source

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

    @Override
    public void onEvent(ServerListChangeEvent event) {
        // do nothing in http client
    }
    
    @Override
    public Class<? extends Event> subscribeType() {
        return ServerListChangeEvent.class;
    }
    
    @Override
    public void registerService(String serviceName, String groupName, Instance instance)
        throws NacosException {
        NAMING_LOGGER.info("[REGISTER-SERVICE] {} registering service {} with instance: {}",
            namespaceId, serviceName,
            instance);
        String groupedServiceName = NamingUtils.getGroupedName(serviceName, groupName);
        if (instance.isEphemeral()) {
            throw new UnsupportedOperationException(
                "Do not support register ephemeral instances by HTTP, please use gRPC replaced.");
        }
        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

View on GitHub (pinned to 9b989acdf1)

Solutions

Switch the client to gRPC mode (the default in Nacos 2.x+) so ephemeral instances are supported.
If HTTP is required, set instance.setEphemeral(false) to register as a persistent instance.
Review the NamingService factory configuration to ensure gRPC is enabled.

Example fix

// before (ephemeral default true + HTTP proxy)
Instance inst = new Instance("1.2.3.4", 8080);
namingService.registerInstance(serviceName, inst);

// after
Instance inst = new Instance("1.2.3.4", 8080);
inst.setEphemeral(false);
namingService.registerInstance(serviceName, inst);

Defensive patterns

Strategy: validation

Validate before calling

// Ensure gRPC transport is used for ephemeral instances.
// In client properties, do not force HTTP:
// Properties props = new Properties();
// props.setProperty("serverAddr", "host:8848");
// NamingService uses gRPC by default in 2.x+.
if (instance.isEphemeral() && isHttpProxy) {
    instance.setEphemeral(false); // or switch to gRPC
}

Try / catch

try {
    namingService.registerInstance(serviceName, instance);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("ephemeral")) {
        // switch to gRPC or set ephemeral=false and retry
        instance.setEphemeral(false);
        namingService.registerInstance(serviceName, instance);
    } else {
        throw e;
    }
}

Prevention

Use the default (gRPC) transport for ephemeral instance registration.
If HTTP is required, always set instance.setEphemeral(false).
Document which services use HTTP vs gRPC to avoid transport/instance-type mismatches.

When it happens

Trigger: The client is configured to use the HTTP naming proxy (serverList with HTTP) and registerService is called with an ephemeral instance (the default for Instance.isEphemeral is true in many constructors).

Common situations: Client configured for HTTP-only communication (older setups or explicit HTTP preference); creating an Instance without setting ephemeral=false and using the HTTP proxy; migrating from HTTP to gRPC without updating the client configuration.

Related errors

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