alibaba/nacos · error · NacosApiException

20004

20004

Error message

Client id %s not exist.

What it means

Thrown by ClientServiceImpl.getClientDetail when clientManager.getClient(clientId) returns null. Error code NOT_FOUND=404 with ErrorCode.RESOURCE_NOT_FOUND=20004. The client (gRPC connection-based or IP-port-based) is not currently registered on this server node.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/core/ClientServiceImpl.java:82

    @Resource
    private ConnectionManager connectionManager;
    
    @Resource
    private ClientServiceIndexesManager clientServiceIndexesManager;
    
    @Resource
    private DistroMapper distroMapper;
    
    @Override
    public List<String> getClientList() {
        return new ArrayList<>(clientManager.allClientId());
    }
    
    @Override
    public ClientSummaryInfo getClientDetail(String clientId) throws NacosApiException {
        Client client = clientManager.getClient(clientId);
        if (null == client) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
                String.format("Client id %s not exist.", clientId));
        }
        ClientSummaryInfo result = new ClientSummaryInfo();
        result.setClientId(client.getClientId());
        result.setEphemeral(client.isEphemeral());
        result.setLastUpdatedTime(client.getLastUpdatedTime());
        result.setClientType("ipPort");
        if (client instanceof ConnectionBasedClient) {
            // upper 2.x client
            result.setClientType("connection");
            Connection connection = connectionManager.getConnection(clientId);
            ConnectionMeta connectionMetaInfo = connection.getMetaInfo();
            result.setConnectType(connectionMetaInfo.getConnectType());
            result.setAppName(connectionMetaInfo.getAppName());
            result.setVersion(connectionMetaInfo.getVersion());
            result.setClientIp(connectionMetaInfo.getClientIp());
            result.setClientPort(connectionMetaInfo.getRemotePort());
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Verify the clientId is active by listing all clients (getClientList) first.
  2. Route the query to the Nacos server node that owns the client (check the /distro responsible-server endpoint).
  3. Confirm the client application is running and its gRPC connection to Nacos is active.
  4. Re-establish the client connection if it was unintentionally dropped.
Defensive patterns

Strategy: try-catch

Validate before calling

List<String> clientIds = clientService.getClientList();
if (!clientIds.contains(clientId)) {
    // client may be on another node or disconnected
    log.warn("clientId {} not found on this node", clientId);
}

Try / catch

try {
    ClientSummaryInfo info = clientService.getClientDetail(clientId);
} catch (NacosApiException e) {
    if (ErrorCode.RESOURCE_NOT_FOUND.getCode() == e.getErrCode()
            || e.getErrCode() == NacosException.NOT_FOUND) {
        // client gone; refresh the client list or route to owning node
    } else { throw e; }
}

Prevention

When it happens

Trigger: Calling the client-service getClientDetail(clientId) admin operation with a clientId that does not map to an active Client in the ClientManager. This happens when the connection has closed or the client never connected to this node.

Common situations: Client disconnected (connection timeout, client shutdown, network drop). Querying a client connected to a different server node. Stale clientId from a previous session. Client heartbeat expired and the client was evicted.

Related errors

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