apache/cassandra · error · RuntimeException

Unknown BufferPool metric name

Error message

Unknown BufferPool metric name 

What it means

NodeProbe.getBufferPoolMetric(String poolType, String metricName) throws when metricName is not one of the handled buffer-pool metric names (e.g. Size, Capacity, Hits, Misses). The name is mapped to a JMX MBean under org.apache.cassandra.metrics:type=BufferPool and unknown names are rejected in the default branch.

Source

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

    {
        try
        {
            switch (metricName)
            {
                case "UsedSize":
                case "OverflowSize":
                case "Capacity":
                case "Size":
                    return JMX.newMBeanProxy(mbeanServerConn,
                           new ObjectName("org.apache.cassandra.metrics:type=BufferPool,scope=" + poolType + ",name=" + metricName),
                           CassandraMetricsRegistry.JmxGaugeMBean.class).getValue();
                case "Hits":
                case "Misses":
                    return JMX.newMBeanProxy(mbeanServerConn,
                    new ObjectName("org.apache.cassandra.metrics:type=BufferPool,scope=" + poolType + ",name=" + metricName),
                    CassandraMetricsRegistry.JmxMeterMBean.class).getCount();
                default:
                    throw new RuntimeException("Unknown BufferPool metric name " + metricName);
            }
        }
        catch (MalformedObjectNameException e)
        {
            throw new RuntimeException(e);
        }
    }

    /**
     * Retrieve a CQL metric value by name. Works generically for any metric registered under
     * {@code org.apache.cassandra.metrics:type=CQL,name=<metricName>} by inspecting the MBean
     * attributes at runtime, without requiring knowledge of the underlying metric type.
     */
    public Object getCQLMetric(String metricName)
    {
        try
        {
            ObjectName objectName = new ObjectName(DefaultNameFactory.GROUP_NAME + ":type=" + CQLMetrics.TYPE_NAME + ",name=" + metricName);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use a supported name exactly: Size, Capacity, Hits, Misses (per the switch cases in your version)
2. Check `nodetool help` output for the buffer pool metric options
3. Browse org.apache.cassandra.metrics:type=BufferPool MBeans in JMX to see available attributes

Example fix

// before
Object v = probe.getBufferPoolMetric("chunk-cache", "Allocations");
// after
Object v = probe.getBufferPoolMetric("chunk-cache", "Hits");

java.util.Set<String> VALID = Set.of("Size","Capacity","Hits","Misses");
if (!VALID.contains(metricName)) throw new IllegalArgumentException("Unknown BufferPool metric: " + metricName);

try { return probe.getBufferPoolMetric(poolType, metricName); } catch (RuntimeException e) { throw new IllegalArgumentException("Supported BufferPool metrics: Size, Capacity, Hits, Misses", e); }

When it happens

Trigger: Running the nodetool buffer-pool metrics command with an unsupported metric name, e.g. 'Allocations' or 'size' (wrong case).

Common situations: Case-sensitivity mistakes; expecting metrics not exposed in the installed Cassandra version; scripting from documentation of a different release.

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 Cache metric name
• Error while refreshing system.size_estimates
• Timeout type requires one of (read, range, write, counterwri
• timeout must be non-negative
• Error setting log for on level . Please check logback confi

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