alibaba/nacos · error · NacosRuntimeException

-401

-401

Error message

Client [%s] connection already disconnect, can't register ephemeral instance.

What it means

Thrown by EphemeralClientOperationServiceImpl.checkClientIsLegal when the Client retrieved by clientId from clientManager is null — meaning the gRPC/HTTP connection for that clientId has been disconnected and the Client object was removed. Error code -401 (CLIENT_DISCONNECT) via NacosRuntimeException. The server cannot register an ephemeral instance against a connection that no longer exists.

Source

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

            new ClientOperationEvent.ClientSubscribeServiceEvent(singleton, clientId));
    }
    
    @Override
    public void unsubscribeService(Service service, Subscriber subscriber, String clientId) {
        Service singleton =
            ServiceManager.getInstance().getSingletonIfExist(service).orElse(service);
        Client client = clientManager.getClient(clientId);
        checkClientIsLegal(client, clientId);
        client.removeServiceSubscriber(singleton);
        client.setLastUpdatedTime();
        NotifyCenter.publishEvent(
            new ClientOperationEvent.ClientUnsubscribeServiceEvent(singleton, clientId));
    }
    
    private void checkClientIsLegal(Client client, String clientId) {
        if (client == null) {
            Loggers.SRV_LOG.warn("Client connection {} already disconnect", clientId);
            throw new NacosRuntimeException(NacosException.CLIENT_DISCONNECT,
                String.format(
                    "Client [%s] connection already disconnect, can't register ephemeral instance.",
                    clientId));
        }
        if (!client.isEphemeral()) {
            Loggers.SRV_LOG.warn("Client connection {} type is not ephemeral", clientId);
            throw new NacosRuntimeException(NacosException.INVALID_PARAM,
                String.format(
                    "Current client [%s] is persistent client, can't register ephemeral instance.",
                    clientId));
        }
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Ensure the client SDK re-establishes the gRPC connection (and gets a new clientId) before retrying registration.
2. Check client-side connection health and reconnect logic (the SDK should auto-reconnect on CLIENT_DISCONNECT).
3. Increase server-side client idle timeout if connections are being evicted prematurely (nacos.remote.client.grpc.timeout).
4. If the error persists, restart the client application to force a clean reconnection.

Client client = clientManager.getClient(clientId);
if (client == null) {
    // connection lost — client SDK must reconnect and obtain a new clientId
    // before retrying registration
    return;
}

try {
    ephemeralClientOperationService.registerInstance(service, instance, clientId);
} catch (NacosRuntimeException e) {
    if (e.getErrCode() == NacosException.CLIENT_DISCONNECT) {
        // -401: reconnect via SDK, then retry with the new clientId
    } else throw e;
}

When it happens

Trigger: A register/deregister/subscriber operation arrives for a clientId whose underlying gRPC connection has been closed (client crashed, network drop, idle-timeout eviction). The ClientManager has already removed the Client, so getClient returns null.

Common situations: Client process crashed or was killed without graceful disconnect. gRPC connection idle timeout fired on the server side. Network partition between client and server. Server restarted and lost all in-memory client connections; clients retry before re-establishing the connection.

Related errors

• -401
• SERVER_ERROR
• {e.getErrCode()}
• Failed to acquire lock: {}
• 500

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