{"record":{"id":"ed30bb1593c34dc5","repo":"alibaba/nacos","slug":"400-ed30bb","errorCode":"400","errorMessage":"Current service %s is persistent service, can't register ephemeral instance.","messagePattern":"Current service (.+?) is persistent service, can't register ephemeral instance\\.","errorType":"validation","errorClass":"NacosRuntimeException","httpStatus":null,"severity":"error","filePath":"naming/src/main/java/com/alibaba/nacos/naming/core/v2/service/impl/EphemeralClientOperationServiceImpl.java","lineNumber":62,"sourceCode":" * @author xiweng.yy\n */\n@Component(\"ephemeralClientOperationService\")\npublic class EphemeralClientOperationServiceImpl implements ClientOperationService {\n    \n    private final ClientManager clientManager;\n    \n    public EphemeralClientOperationServiceImpl(ClientManagerDelegate clientManager) {\n        this.clientManager = clientManager;\n    }\n    \n    @Override\n    public void registerInstance(Service service, Instance instance, String clientId)\n        throws NacosException {\n        NamingUtils.checkInstanceIsLegal(instance);\n        \n        Service singleton = ServiceManager.getInstance().getSingleton(service);\n        if (!singleton.isEphemeral()) {\n            throw new NacosRuntimeException(NacosException.INVALID_PARAM,\n                String.format(\n                    \"Current service %s is persistent service, can't register ephemeral instance.\",\n                    singleton.getGroupedServiceName()));\n        }\n        Client client = clientManager.getClient(clientId);\n        checkClientIsLegal(client, clientId);\n        InstancePublishInfo instanceInfo = getPublishInfo(instance);\n        client.addServiceInstance(singleton, instanceInfo);\n        client.setLastUpdatedTime();\n        client.recalculateRevision();\n        NotifyCenter\n            .publishEvent(new ClientOperationEvent.ClientRegisterServiceEvent(singleton, clientId));\n        NotifyCenter\n            .publishEvent(new MetadataEvent.InstanceMetadataEvent(singleton,\n                instanceInfo.getMetadataId(), false));\n    }\n    \n    @Override","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/core/v2/service/impl/EphemeralClientOperationServiceImpl.java#L44-L80","documentation":"Thrown by EphemeralClientOperationServiceImpl.registerInstance when the resolved service singleton is NOT ephemeral (singleton.isEphemeral() returns false) but the registration targets the ephemeral path. Error code 400 (INVALID_PARAM) via NacosRuntimeException. Nacos enforces instance-type/service-type consistency: an ephemeral instance can only be registered against an ephemeral service.","triggerScenarios":"A client (gRPC or HTTP) registers an ephemeral instance against a service that was created with ephemeral=false (persistent). The service singleton's ephemeral flag is authoritative — it is set at service creation time and cannot be mixed.","commonSituations":"Service was created as persistent (e.g. via the v1 API or explicit ephemeral=false) but the client SDK defaults to ephemeral=true. Migration from v1 to v2 naming where the ephemeral flag was not aligned. Different teams creating the service and registering instances with mismatched ephemeral settings.","solutions":["Align the instance's ephemeral flag with the service's: if the service is persistent, register via the persistent path (PersistentClientOperationServiceImpl).","Recreate the service with ephemeral=true if ephemeral instances are intended, after deregistering all existing instances.","In the client SDK, explicitly set instance.setEphemeral(true/false) to match the service definition.","Query the service metadata to check its ephemeral flag before registering."],"exampleFix":"// before — service is persistent, client registers ephemeral\nInstance inst = new Instance();\ninst.setEphemeral(true); // mismatch!\nnamingService.registerInstance(service, inst);\n\n// after — match service type, or recreate service as ephemeral\nInstance inst = new Instance();\ninst.setEphemeral(false); // persistent to match service\nnamingService.registerInstance(service, inst);","handlingStrategy":"validation","validationCode":"Service singleton = ServiceManager.getInstance().getSingleton(service);\nboolean isEphemeralService = singleton.isEphemeral();\nif (isEphemeralService != instance.isEphemeral()) {\n    // mismatch — align flags or route to the correct operation service\n    instance.setEphemeral(isEphemeralService);\n}\nephemeralClientOperationService.registerInstance(service, instance, clientId);","typeGuard":null,"tryCatchPattern":"try {\n    ephemeralClientOperationService.registerInstance(service, instance, clientId);\n} catch (NacosRuntimeException e) {\n    if (e.getErrCode() == NacosException.INVALID_PARAM\n            && e.getMessage().contains(\"persistent service\")) {\n        // route to persistent registration path instead\n        persistentClientOperationService.registerInstance(service, instance, clientId);\n    } else throw e;\n}","preventionTips":["Always set instance.setEphemeral() to match the service definition.","Query service metadata to confirm the ephemeral flag before registering.","Use a single ephemeral convention per service across all clients."],"tags":["naming","instance-register","ephemeral","type-mismatch","validation"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}