apache/cassandra · error · java.lang.IllegalArgumentException

Invalid value %d for %s: maximum allowed value is %d

Error message

Invalid value %d for %s: maximum allowed value is %d

What it means

GuardrailsOptions.validatePositiveNumeric validates numeric guardrail thresholds: -1 means disabled, 0 is a valid trigger-above-zero threshold, and any value above the guardrail's maximum (or negative) is rejected with IllegalArgumentException. This enforces per-guardrail upper limits in cassandra.yaml / guardrails config.

Source

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

    }

    private static <T> void updatePropertyWithLogging(String propertyName, T newValue, Supplier<T> getter, Consumer<T> setter)
    {
        T oldValue = getter.get();
        if (newValue == null || !newValue.equals(oldValue))
        {
            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");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Set the value to at most the printed maximum for that guardrail
  2. Use -1 to disable the guardrail (not other negatives)
  3. Use 0 if the intent is 'any value above zero triggers'
  4. Check the guardrail's definition for its max constant

Example fix

// before (max 256)
fields_per_table:
  warn_threshold: 1000
// after
fields_per_table:
  warn_threshold: 200
Defensive patterns

Strategy: validation

Validate before calling

static void checkGuardrailValue(long v, long max, String name) {
    if (v == -1 || v == 0) return;
    if (v > max) throw new IllegalArgumentException(name + " max is " + max);
    if (v < 0) throw new IllegalArgumentException(name + " negative not allowed; use -1 to disable");
}

Try / catch

try {
    guardrails.setFieldsPerTableWarn(1000);
} catch (IllegalArgumentException e) {
    logger.error("Guardrail value rejected: {}", e.getMessage());
}

Prevention

When it happens

Trigger: Setting a numeric guardrail (e.g. partition_size_in_mb style thresholds, fields_per_table, collections_per_inner_table limits) to a value larger than that guardrail's defined maximum, via YAML or a guardrails setter.

Common situations: Typo adding an extra digit; copying a limit from another cluster with different caps; setting -2/-5 intending 'disabled' instead of the documented -1.

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