apache/cassandra · error · IllegalArgumentException

The warn threshold %d for %s_warn_threshold should be lower

Error message

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

What it means

For 'max-style' guardrails (where higher is worse), the warn threshold must be lower than (or equal to) the fail threshold. validateWarnLowerThanFail() throws IllegalArgumentException when fail < warn, unless either threshold is -1 (disabled). Note the message wording swaps the displayed order: the first number shown is warn, the second is fail.

Source

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

    public static void validateTimestampThreshold(DurationSpec.LongMicrosecondsBound warn,
                                                  DurationSpec.LongMicrosecondsBound fail,
                                                  String name)
    {
        // this function is used for both upper and lower thresholds because lower threshold is relative
        // despite using MinThreshold we still want the warn threshold to be less than or equal to
        // the fail threshold.
        validateMaxLongThreshold(warn == null ? -1 : warn.toMicroseconds(),
                                 fail == null ? -1 : fail.toMicroseconds(),
                                 name);
    }

    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.
     */

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Swap or adjust the two values so warn <= fail (warn fires earlier than fail).
  2. Set one threshold to -1 if that side should be disabled.
  3. Re-read the message carefully: first number is the warn threshold, second is the fail threshold.

Example fix

// before
partition_size_in_mb_warn_threshold: 1000
partition_size_in_mb_fail_threshold: 500
// after
partition_size_in_mb_warn_threshold: 500
partition_size_in_mb_fail_threshold: 1000
Defensive patterns

Strategy: validation

Validate before calling

if (warn != -1 && fail != -1 && fail < warn) throw new IllegalArgumentException("warn (" + warn + ") must be <= fail (" + fail + ") for max-style guardrail");

Try / catch

try { validateThresholdPair(warn, fail); } catch (IllegalArgumentException e) { log.error("Guardrail thresholds inverted: {}", e.getMessage()); throw e; }

Prevention

When it happens

Trigger: Configuring any max-type guardrail pair like partition_size_in_mb, collection_size, percentage thresholds, or timestamp thresholds with warn > fail, e.g. 'some_warn_threshold: 1000' with 'some_fail_threshold: 500' in cassandra.yaml or via live update.

Common situations: Copy-paste swaps of the two values in cassandra.yaml; incrementing the warn threshold past the fail threshold during tuning; tools generating config that assumes warn-first ordering but assigns larger values to warn.

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/a9d7647574bd0507. Report an issue: GitHub.