alibaba/nacos · error · NacosRuntimeException

400

400

Error message

Current service %s is persistent service, can't register ephemeral instance.

What it means

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.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/core/v2/service/impl/EphemeralClientOperationServiceImpl.java:62

 * @author xiweng.yy
 */
@Component("ephemeralClientOperationService")
public class EphemeralClientOperationServiceImpl implements ClientOperationService {
    
    private final ClientManager clientManager;
    
    public EphemeralClientOperationServiceImpl(ClientManagerDelegate clientManager) {
        this.clientManager = clientManager;
    }
    
    @Override
    public void registerInstance(Service service, Instance instance, String clientId)
        throws NacosException {
        NamingUtils.checkInstanceIsLegal(instance);
        
        Service singleton = ServiceManager.getInstance().getSingleton(service);
        if (!singleton.isEphemeral()) {
            throw new NacosRuntimeException(NacosException.INVALID_PARAM,
                String.format(
                    "Current service %s is persistent service, can't register ephemeral instance.",
                    singleton.getGroupedServiceName()));
        }
        Client client = clientManager.getClient(clientId);
        checkClientIsLegal(client, clientId);
        InstancePublishInfo instanceInfo = getPublishInfo(instance);
        client.addServiceInstance(singleton, instanceInfo);
        client.setLastUpdatedTime();
        client.recalculateRevision();
        NotifyCenter
            .publishEvent(new ClientOperationEvent.ClientRegisterServiceEvent(singleton, clientId));
        NotifyCenter
            .publishEvent(new MetadataEvent.InstanceMetadataEvent(singleton,
                instanceInfo.getMetadataId(), false));
    }
    
    @Override

View on GitHub (pinned to 9b989acdf1)

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.

Example fix

// before — service is persistent, client registers ephemeral
Instance inst = new Instance();
inst.setEphemeral(true); // mismatch!
namingService.registerInstance(service, inst);

// after — match service type, or recreate service as ephemeral
Instance inst = new Instance();
inst.setEphemeral(false); // persistent to match service
namingService.registerInstance(service, inst);

Defensive patterns

Strategy: validation

Validate before calling

Service singleton = ServiceManager.getInstance().getSingleton(service);
boolean isEphemeralService = singleton.isEphemeral();
if (isEphemeralService != instance.isEphemeral()) {
    // mismatch — align flags or route to the correct operation service
    instance.setEphemeral(isEphemeralService);
}
ephemeralClientOperationService.registerInstance(service, instance, clientId);

Try / catch

try {
    ephemeralClientOperationService.registerInstance(service, instance, clientId);
} catch (NacosRuntimeException e) {
    if (e.getErrCode() == NacosException.INVALID_PARAM
            && e.getMessage().contains("persistent service")) {
        // route to persistent registration path instead
        persistentClientOperationService.registerInstance(service, instance, clientId);
    } else throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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