apache/cassandra · error · IllegalArgumentException

The warn threshold %d for %s_warn_threshold should be greate

Error message

The warn threshold %d for %s_warn_threshold should be greater than the fail threshold %d

What it means

For 'min-style' guardrails (where lower is worse, e.g. minimum_replication_factor), the warn threshold must be greater than (or equal to) the fail threshold. validateWarnGreaterThanFail() throws IllegalArgumentException when fail > warn, unless either threshold is -1 (disabled).

Source

Thrown at src/java/org/apache/cassandra/config/GuardrailsOptions.java:1596

    }

    private static void validateWarnLowerThanFail(long warn, long fail, String name)
    {
        if (warn == -1 || fail == -1)
            return;

        if (fail < warn)
            throw new IllegalArgumentException(format("The warn threshold %d for %s_warn_threshold should be lower " +
                                                      "than the fail threshold %d", warn, name, fail));
    }

    private static void validateWarnGreaterThanFail(long warn, long fail, String name)
    {
        if (warn == -1 || fail == -1)
            return;

        if (fail > warn)
            throw new IllegalArgumentException(format("The warn threshold %d for %s_warn_threshold should be greater " +
                                                      "than the fail threshold %d", warn, name, fail));
    }

    /**
     * A {@code null} size disables a size threshold, and a size of zero bytes is a valid threshold meaning "any
     * value above zero bytes triggers the guardrail", so the only thing left to check is the relative order of the
     * two thresholds. {@link DataStorageSpec} already rejects negative sizes when parsing.
     */
    private static void validateSizeThreshold(DataStorageSpec.LongBytesBound warn, DataStorageSpec.LongBytesBound fail, String name)
    {
        validateWarnLowerThanFail(warn, fail, name);
    }

    private static void validateWarnLowerThanFail(DataStorageSpec.LongBytesBound warn, DataStorageSpec.LongBytesBound fail, String name)
    {
        if (warn == null || fail == null)
            return;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Set the warn threshold >= the fail threshold (warnings fire before hard failures as the value drops).
  2. Set one of the thresholds to -1 to disable that side.
  3. Confirm which guardrail family (min vs max) you are configuring and apply the correct ordering.

Example fix

// before
minimum_replication_factor_warn_threshold: 2
minimum_replication_factor_fail_threshold: 4
// after
minimum_replication_factor_warn_threshold: 4
minimum_replication_factor_fail_threshold: 2
Defensive patterns

Strategy: validation

Validate before calling

if (warn != -1 && fail != -1 && fail > warn) throw new IllegalArgumentException("for min-style guardrails warn (" + warn + ") must be >= fail (" + fail + ")");

Try / catch

try { validateMinThresholdPair(warn, fail); } catch (IllegalArgumentException e) { log.error("Min-guardrail thresholds inverted: {}", e.getMessage()); throw e; }

Prevention

When it happens

Trigger: Configuring a min-type guardrail such as minimum_replication_factor with warn < fail, e.g. 'minimum_replication_factor_warn_threshold: 2' with 'minimum_replication_factor_fail_threshold: 4'; validation runs at startup and on live guardrail updates.

Common situations: Reusing a max-guardrail template (warn < fail) for a min-guardrail where ordering is inverted; hand edits lowering the warn threshold below the fail threshold while tuning.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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