apache/cassandra · error · java.lang.IllegalArgumentException

Invalid value %d for %s: negative values are not allowed, ou

Q: What causes "Invalid value %d for %s: negative values are not allowed, outside of -1 which disables the guardrail" in apache/cassandra?

Change the offending threshold to a non-negative value (0 is valid and means 'any value above zero triggers').

Error message

Invalid value %d for %s: negative values are not allowed, outside of -1 which disables the guardrail

What it means

GuardrailsOptions.validatePositiveNumeric() validates numeric guardrail thresholds in cassandra.yaml (or via live guardrail updates). Any value below 0 other than the special -1 'disabled' sentinel is rejected with this IllegalArgumentException. This includes 0 being valid (any value above zero triggers the guardrail), so only values <= -2 trigger it.

Source

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

        {
            setter.accept(newValue);
            logger.info("Updated {} from {} to {}", propertyName, oldValue, newValue);
        }
    }

    private static void validatePositiveNumeric(long value, long maxValue, String name)
    {
        if (value == -1)
            return;

        if (value > maxValue)
            throw new IllegalArgumentException(format("Invalid value %d for %s: maximum allowed value is %d",
                                                      value, name, maxValue));

        // Zero is a valid threshold, meaning "any value above zero triggers the guardrail". 
        // We allow -1 as a general "disabling" flag, but reject anything lower to avoid mistakes.
        if (value < 0)
            throw new IllegalArgumentException(format("Invalid value %d for %s: negative values are not allowed, " +
                                                      "outside of -1 which disables the guardrail", value, name));
    }

    private static void validatePercentage(long value, String name)
    {
        validatePositiveNumeric(value, 100, name);
    }

    private static void validatePercentageThreshold(int warn, int fail, String name)
    {
        validatePercentage(warn, name + "_warn_threshold");
        validatePercentage(fail, name + "_fail_threshold");
        validateWarnLowerThanFail(warn, fail, name);
    }

    private static void validateMaxIntThreshold(int warn, int fail, String name)
    {
        validatePositiveNumeric(warn, Integer.MAX_VALUE, name + "_warn_threshold");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Change the offending threshold to a non-negative value (0 is valid and means 'any value above zero triggers').
If the intent was to disable the guardrail, set the value to exactly -1.
If the value came from a script/templating variable, fix the variable source so it produces a valid integer (>= 0 or -1).

Example fix

// cassandra.yaml before
read_before_write_consistency_levels_warn_threshold: -5
// after (disable)
read_before_write_consistency_levels_warn_threshold: -1
// after (valid threshold)
read_before_write_consistency_levels_warn_threshold: 0

Defensive patterns

Strategy: validation

Validate before calling

long v = configuredThreshold;
if (v < 0 && v != -1) throw new IllegalArgumentException("threshold must be >= 0 or exactly -1 to disable, got " + v);

Try / catch

try { applyGuardrailConfig(cfg); } catch (IllegalArgumentException e) { log.error("Bad guardrail threshold: {}", e.getMessage()); throw e; }

Prevention

Remember: 0 is a valid threshold (triggers above zero); -1 disables; anything else negative is rejected.
Lint cassandra.yaml guardrail values in CI before deployment.
Source threshold values from constants, not ad-hoc script variables.

When it happens

Trigger: Setting any guardrail threshold such as read_before_write_consistency_levels_warn_threshold, partition_size_in_mb thresholds, or percentage thresholds to a negative value other than -1, e.g. cassandra.yaml containing 'some_guardrail_warn_threshold: -50', or passing a negative value through Config#setGuardrails / guardrail setter at startup or via a config update.

Common situations: Operators hand-editing cassandra.yaml and using -1, -2 or other negatives intending to 'disable' or 'lower' a guardrail; scripts templating thresholds with uninitialized negative variables; copying a -1 disable flag but adding an offset; upgrading from configs where -1 semantics differed.

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

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