apache/cassandra · error · ConfigurationException

Invalid guardrails configuration:

Error message

Invalid guardrails configuration: 

What it means

GuardrailsOptions validates its configuration with IllegalArgumentException; DatabaseDescriptor wraps that into a ConfigurationException with the prefix 'Invalid guardrails configuration: ' plus the underlying message, so guardrails misconfiguration fails startup with a clear cause chain.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1405

        if (writeTombstoneWarn != -1 && writeTombstoneWarn < minTrackedTombstoneCount)
            throw new ConfigurationException(String.format("write_tombstone_warn_threshold (%d) cannot be less than min_tracked_partition_tombstone_count (%d)",
                                                           writeTombstoneWarn, minTrackedTombstoneCount));
    }

    public static GuardrailsOptions getGuardrailsConfig()
    {
        return guardrails;
    }

    private static void applyGuardrails()
    {
        try
        {
            guardrails = new GuardrailsOptions(conf);
        }
        catch (IllegalArgumentException e)
        {
            throw new ConfigurationException("Invalid guardrails configuration: " + e.getMessage(), e);
        }
    }

    // TODO (expected): move all of the Accord config setup and accessors into AccordConfig
    private static void applyAccord()
    {
        try
        {
            accordProgressLogConfig = new DefaultProgressLog.Config();
            accordProgressLogConfig.concurrency = conf.accord.progress_log_concurrency.or(32);
            accordProgressLogConfig.maxActiveRunTime = conf.accord.progress_log_query_fallback_timeout.toDuration();
        }
        catch (IllegalArgumentException e)
        {
            throw new ConfigurationException("Invalid accord progress log configuration: " + e.getMessage(), e);
        }
        AccordService.applyProtocolModifiers(getAccord());
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Read the wrapped e.getMessage() after the prefix for the exact offending guardrail
2. Fix the ordering so warn thresholds are <= fail thresholds
3. Correct or remove the invalid guardrail value in cassandra.yaml
4. Validate the config against the GuardrailsOptions docs for your Cassandra version

Example fix

// before (cassandra.yaml)
guardrails:
  partition_keys_in_select_warn_threshold: 100
  partition_keys_in_select_fail_threshold: 50
// after
guardrails:
  partition_keys_in_select_warn_threshold: 50
  partition_keys_in_select_fail_threshold: 100

try { new GuardrailsOptions(conf); } catch (IllegalArgumentException e) { preflightFail("guardrails: " + e.getMessage()); }

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { LOG.error("Guardrails config rejected: " + e.getMessage()); System.exit(1); }

When it happens

Trigger: Any guardrails setting in cassandra.yaml that GuardrailsOptions rejects (e.g. invalid threshold ordering like rows-per-partition warn > fail, unknown/disabled guardrail values, bad regexes), during applyGuardrails at startup.

Common situations: Setting a guardrail warn threshold above its fail threshold; enabling a guardrail with a malformed pattern; config copied from a version where a guardrail had different semantics; typos in values (non-numeric where numbers required).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• %s can not be greater than %s
• %s can not be bigger than %s
• %s can not be equal to %s. You set %s and %s respectively.
• %s can not be bigger than %s. You have set %s and %s respect
• The shortest password to pass the failing validator for any

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