apache/cassandra · error · RuntimeException

Error occured when getting the guardrails config

Error message

Error occured when getting the guardrails config

What it means

GuardrailsConfigCommand.display wraps its whole table-building and JMX-consulting logic in a try/catch and rethrows any Throwable as RuntimeException('Error occured when getting the guardrails config'). It is a catch-all indicating the nodetool client failed to retrieve guardrails configuration from the node, typically via NodeProbe/JMX, and the real cause is attached as the suppressed root exception.

Source

Thrown at src/java/org/apache/cassandra/tools/nodetool/GuardrailsConfigCommand.java:467

            else
            {
                if (holder.values().stream().flatMap(list -> Stream.of(list.toArray(new InternalRow[0]))).count() == 1)
                {
                    for (Map.Entry<GuardrailCategory, List<InternalRow>> entry : holder.entrySet())
                        populateOne(tb, entry.getValue());
                }
                else
                {
                    for (Map.Entry<GuardrailCategory, List<InternalRow>> entry : holder.entrySet())
                        populateTable(tb, entry.getValue());
                }
            }

            tb.printTo(probe.output().out);
        }
        catch (Throwable e)
        {
            throw new RuntimeException("Error occured when getting the guardrails config", e);
        }
    }

    private void populateTable(TableBuilder tableBuilder, List<InternalRow> bucket)
    {
        for (InternalRow row : bucket)
            tableBuilder.add(row.name, row.value);
    }

    private void populateOne(TableBuilder tableBuilder, List<InternalRow> bucket)
    {
        if (bucket.size() == 1)
            tableBuilder.add(bucket.get(0).value);
    }

    void constructRow(List<InternalRow> bucket, String guardrailName, String value)
    {
        bucket.add(new InternalRow(guardrailName, value));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Read the chained 'Caused by' stack trace to find the real failure
2. Verify the node is up and JMX is reachable (nodetool status against the same host/port/credentials)
3. Use a nodetool version matching the Cassandra server version so the guardrails MBean exists
4. If MBean/auth is the issue, fix cassandra-env.yml JMX settings or nodetool credentials

Example fix

// before
nodetool -h prod-node-7 guardrails-config   # fails: JMX unreachable
// after
nodetool -h prod-node-7 -p 7199 -u jmxuser -pw jmxpass guardrails-config

// preflight: confirm JMX is reachable and the guardrails MBean exists
nodetool -h $HOST -p 7199 info >/dev/null || { echo "JMX unreachable"; exit 1; }

try { runNodetool("guardrails-config"); } catch (RuntimeException e) {
    Throwable root = e; while (root.getCause()!=null) root=root.getCause();
    log("guardrails-config failed: " + root); // inspect real cause
}

When it happens

Trigger: Running `nodetool guardrails-config` when the JMX connection fails or the remote call throws: node down, wrong host/port, JMX auth failure, MBean missing (older server version without guardrails), or an exception while rendering the internal rows.

Common situations: Pointing nodetool at a node where the storage proxy/JMX service is not up; running a newer nodetool against an older Cassandra that lacks the guardrails MBean; wrong credentials in nodetool/JMX config; firewall blocking port 7199.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Table count warn threshold should be positive, not {value}
• Keyspace count warn threshold should be positive, not {value
• compaction tombstone warning threshold needs to be >= 0, not
• Could not retrieve list of stat mbeans.
• Error while refreshing system.size_estimates

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