What causes "Get Running Client failed: " in alibaba/nacos?

Ensure the client is initialized and connected before using capability-gated APIs (await the first successful config interaction).

alibaba/nacos · error · NacosRuntimeException

{e.getErrCode()}

{e.getErrCode()}

Error message

Get Running Client failed:

What it means

Thrown as a NacosRuntimeException by ClientWorker.isAbilitySupportedByServer when getOneRunningClient() throws a NacosException (e.g. no connected gRPC client available). The wrapper preserves the original errorCode and chains the cause. It occurs when the client tries to query server capability (used for feature gating like fuzzy watch) but no RPC client is connected.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/config/impl/ClientWorker.java:1501

                return getOneRunningClient().isRunning();
            } catch (NacosException e) {
                LOGGER.warn("check server status failed.", e);
                return false;
            }
        }
        
        /**
         * Determine whether nacos-server supports the capability.
         *
         * @param abilityKey ability key
         * @return true if supported, otherwise false
         */
        public boolean isAbilitySupportedByServer(AbilityKey abilityKey) {
            try {
                return getOneRunningClient()
                    .getConnectionAbility(abilityKey) == AbilityStatus.SUPPORTED;
            } catch (NacosException e) {
                throw new NacosRuntimeException(e.getErrCode(), "Get Running Client failed: ", e);
            }
        }
    }
    
    public String getAgentName() {
        return agent.getName();
    }
    
    public ConfigTransportClient getAgent() {
        return agent;
    }
    
}

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure the client is initialized and connected before using capability-gated APIs (await the first successful config interaction).
Do not call feature APIs after client.shutdown().
Inspect the chained NacosException cause to see the underlying connection failure code.
Recreate/restart the ConfigService if the underlying gRPC client was closed.

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure client is connected before capability-gated calls
// (perform one successful getConfig/listen first to establish the gRPC channel)

Try / catch

try {
    boolean supported = client.isAbilitySupportedByServer(AbilityKey.SERVER_FUZZY_WATCH);
} catch (NacosRuntimeException e) {
    log.warn("cannot query server capability, client not connected: {}", e.getErrCode());
    supported = false;
}

Prevention

Establish the gRPC connection (first config interaction) before capability checks.
Do not use capability-gated APIs after shutdown().
Handle the wrapped NacosRuntimeException and inspect the cause.

When it happens

Trigger: Calling a capability-gated feature (fuzzy watch registration, etc.) before the gRPC client is connected, or after the client has been shut down / lost all connections.

Common situations: Invoking fuzzy watch immediately after constructing the ConfigService before the gRPC channel is established, or after a shutdown() call.

Related errors

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