{"record":{"id":"28567ba3d55d1d65","repo":"alibaba/nacos","slug":"do-not-support-register-ephemeral-instances-by-htt","errorCode":null,"errorMessage":"Do not support register ephemeral instances by HTTP, please use gRPC replaced.","messagePattern":"Do not support register ephemeral instances by HTTP, please use gRPC replaced\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/com/alibaba/nacos/client/naming/remote/http/NamingHttpClientProxy.java","lineNumber":141,"sourceCode":"    @Override\n    public void onEvent(ServerListChangeEvent event) {\n        // do nothing in http client\n    }\n    \n    @Override\n    public Class<? extends Event> subscribeType() {\n        return ServerListChangeEvent.class;\n    }\n    \n    @Override\n    public void registerService(String serviceName, String groupName, Instance instance)\n        throws NacosException {\n        NAMING_LOGGER.info(\"[REGISTER-SERVICE] {} registering service {} with instance: {}\",\n            namespaceId, serviceName,\n            instance);\n        String groupedServiceName = NamingUtils.getGroupedName(serviceName, groupName);\n        if (instance.isEphemeral()) {\n            throw new UnsupportedOperationException(\n                \"Do not support register ephemeral instances by HTTP, please use gRPC replaced.\");\n        }\n        final Map<String, String> params = new HashMap<>(32);\n        params.put(CommonParams.NAMESPACE_ID, namespaceId);\n        params.put(CommonParams.SERVICE_NAME, groupedServiceName);\n        params.put(CommonParams.GROUP_NAME, groupName);\n        params.put(CommonParams.CLUSTER_NAME, instance.getClusterName());\n        params.put(IP_PARAM, instance.getIp());\n        params.put(PORT_PARAM, String.valueOf(instance.getPort()));\n        params.put(WEIGHT_PARAM, String.valueOf(instance.getWeight()));\n        params.put(REGISTER_ENABLE_PARAM, String.valueOf(instance.isEnabled()));\n        params.put(HEALTHY_PARAM, String.valueOf(instance.isHealthy()));\n        params.put(EPHEMERAL_PARAM, String.valueOf(instance.isEphemeral()));\n        params.put(META_PARAM, JsonUtils.toJson(instance.getMetadata()));\n        reqApi(UtilAndComs.nacosUrlInstance, params, HttpMethod.POST);\n    }\n    \n    @Override","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/naming/remote/http/NamingHttpClientProxy.java#L123-L159","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before (ephemeral default true + HTTP proxy)\nInstance inst = new Instance(\"1.2.3.4\", 8080);\nnamingService.registerInstance(serviceName, inst);\n\n// after\nInstance inst = new Instance(\"1.2.3.4\", 8080);\ninst.setEphemeral(false);\nnamingService.registerInstance(serviceName, inst);","handlingStrategy":"validation","validationCode":"// Ensure gRPC transport is used for ephemeral instances.\n// In client properties, do not force HTTP:\n// Properties props = new Properties();\n// props.setProperty(\"serverAddr\", \"host:8848\");\n// NamingService uses gRPC by default in 2.x+.\nif (instance.isEphemeral() && isHttpProxy) {\n    instance.setEphemeral(false); // or switch to gRPC\n}","typeGuard":null,"tryCatchPattern":"try {\n    namingService.registerInstance(serviceName, instance);\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage().contains(\"ephemeral\")) {\n        // switch to gRPC or set ephemeral=false and retry\n        instance.setEphemeral(false);\n        namingService.registerInstance(serviceName, instance);\n    } else {\n        throw e;\n    }\n}","preventionTips":["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."],"tags":["naming","http-proxy","ephemeral","registration","client"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}