apache/cassandra · error · RuntimeException

Unknown client metric

Error message

Unknown client metric 

What it means

getClientMetric switches over metricName (connectedNativeClients, connectedNativeClientsByUser, clientsByProtocolVersion, etc.); an unrecognized name falls to default and throws RuntimeException("Unknown client metric " + metricName). This is an explicit unsupported-argument guard, not a JMX connectivity failure.

Solutions

1. Use an exact supported name as listed in NodeProbe's switch (case-sensitive).
2. Enumerate valid names from the NodeProbe source of your Cassandra version.
3. Extend NodeProbe's switch (and rebuild) if the metric exists in JMX but is not yet exposed.
4. Guard the call site with try-catch and fail the report generation with a clear message.

Example fix

// before
probe.getClientMetric("connected_native_clients"); // unknown
// after
probe.getClientMetric("connectedNativeClients");

Set<String> VALID = Set.of("connectedNativeClients", "connectedNativeClientsByUser", "clientsByProtocolVersion");
if (!VALID.contains(metricName)) throw new IllegalArgumentException("Unknown client metric: " + metricName);

try {
    return probe.getClientMetric(metricName);
} catch (RuntimeException e) {
    if (String.valueOf(e.getMessage()).startsWith("Unknown client metric"))
        throw new IllegalArgumentException(e.getMessage() + " — check NodeProbe switch for valid names", e);
    throw e;
}

When it happens

Trigger: Calling getClientMetric with a string outside the supported client-metric set — misspellings, wrong casing, or names from another Cassandra version (e.g. metrics added later like cidr-related or auth metrics).

Common situations: Dashboards built against a newer Cassandra being run against an older one; typos in nodetool-extending scripts; names drifted after Cassandra metric renames.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown compaction metric
• Unknown metric
• appendAll() can only be called on non-frozen collections
• Can not initialize cluster with empty cluster identifier
• Can't abort bootstrap for - it does not exist in cluster…

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/e8c46ac9be37f804. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/NodeProbe.java:2305

    /**
     * Retrieve Proxy metrics
     * @param metricName
     */
    public Object getClientMetric(String metricName)
    {
        try
        {
            switch(metricName)
            {
                case "connections": // List<Map<String,String>> - list of all native connections and their properties
                case "connectedNativeClients": // number of connected native clients
                case "connectedNativeClientsByUser": // number of native clients by username
                case "clientsByProtocolVersion": // number of native clients by protocol version
                    return JMX.newMBeanProxy(mbeanServerConn,
                            new ObjectName("org.apache.cassandra.metrics:type=Client,name=" + metricName),
                            CassandraMetricsRegistry.JmxGaugeMBean.class).getValue();
                default:
                    throw new RuntimeException("Unknown client metric " + metricName);
            }
        }
        catch (MalformedObjectNameException e)
        {
            throw new RuntimeException(e);
        }
    }

    public Object getCidrFilteringMetric(String metricName)
    {
        try
        {
            switch(metricName)
            {
                case CIDRAuthorizerMetrics.CIDR_CHECKS_LATENCY:
                    return JMX.newMBeanProxy(mbeanServerConn,
                                             new ObjectName("org.apache.cassandra.metrics:type=CIDRAuthorization,name="
                                                            + metricName),

View on GitHub (pinned to 88fd0f6a0e)