apache/cassandra · error · IllegalStateException

Guardrail %s not found.

Error message

Guardrail %s not found.

What it means

When querying a specific guardrail by name, nodetool guardrails-config looks up matching getter methods on the GuardrailsMBean; if none match it throws IllegalStateException 'Guardrail <name> not found.', meaning no such guardrail getter exists on the server.

Source

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

        @Option(names = { "--expand" },
        description = "Expand all guardrail names so they reflect their counterparts in cassandra.yaml")
        private boolean expand = false;

        @Parameters(index = "0", arity = "0..1", description = "Specific name of a guardrail to get configuration of or all guardrails if not specified.")
        private String guardrailName;

        @Override
        public void execute(NodeProbe probe)
        {
            if (guardrailName != null && guardrailCategory != null)
                throw new IllegalStateException("Do not specify additional arguments when --category/-c is set.");

            Map<String, List<Method>> allGetters = parseGuardrailNames(probe.getGuardrailsMBean().getClass().getDeclaredMethods(), guardrailName);

            if (allGetters.isEmpty())
            {
                assert guardrailName != null;
                throw new IllegalStateException(format("Guardrail %s not found.", guardrailName));
            }

            display(probe, allGetters, guardrailCategory, expand);
        }

        @VisibleForTesting
        public static Map<String, List<Method>> parseGuardrailNames(Method[] guardrailsMethods, String guardrailName)
        {
            Map<String, List<Method>> allGetters = stream(guardrailsMethods)
                                                   .filter(method -> method.getName().startsWith("get")
                                                                     && !method.getName().endsWith("CSV")
                                                                     && !(method.getName().endsWith("WarnThreshold") || method.getName().endsWith("FailThreshold")))
                                                   .filter(method -> guardrailName == null || guardrailName.equals(toSnakeCase(method.getName().substring(3))))
                                                   .collect(Collectors.groupingBy(method -> toSnakeCase(method.getName().substring(3))));

            // TODO for now remove custom guardrails
            for (String ignore : ignored)
                allGetters.remove(ignore);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Run `nodetool guardrailsconfig` with no arguments to list all available guardrails and copy the exact name.
2. Check the Cassandra version's GuardrailsMBean for the correct name.
3. Fix the name's casing/naming convention to match the MBean getter.

Example fix

// before
nodetool guardrailsconfig get readconsistancylevel
// after
nodetool guardrailsconfig get read_consistency_level

available = subprocess.run(['nodetool','guardrailsconfig'], capture_output=True, text=True).stdout
def validate_guardrail(name):
    if name not in available:
        raise SystemExit(f'unknown guardrail: {name}')

try:
    run(['nodetool','guardrailsconfig','get',name])
except subprocess.CalledProcessError:
    sys.exit(f'guardrail {name!r} not found on this node/version')

When it happens

Trigger: Running `nodetool guardrailsconfig get <name>` where <name> does not correspond to any declared getter method on the Guardrails MBean (typo or guardrail unavailable in this Cassandra version).

Common situations: Typo in the guardrail name; querying a guardrail introduced in a newer Cassandra release than the node runs; using camelCase where snake_case is expected (or vice versa).

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Do not specify additional arguments when --category/-c is se
• Unhandled return type:
• No arguments.
• Error occured when setting the config for setter %s with arg
• %s is expecting %d argument values. Getting %d instead.

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