apache/cassandra · error · IllegalArgumentException

Invalid data rate: ${value}. It shouldn't be more than ${max

Error message

Invalid data rate: ${value}. It shouldn't be more than ${max-1} in ${minUnit}

What it means

After parsing a rate string, DataRateSpec validates that the converted quantity in the minimum unit is below a configured maximum. If the value equals or exceeds the max, this IllegalArgumentException is thrown showing the largest allowed value (max-1) in the minimum unit.

Source

Thrown at src/java/org/apache/cassandra/config/DataRateSpec.java:80

    {
        this(value);

        validateQuantity(value, quantity(), unit(), minUnit, max);
    }

    private DataRateSpec(long quantity, DataRateUnit unit, DataRateUnit minUnit, long max)
    {
        this.quantity = quantity;
        this.unit = unit;

        validateQuantity(quantity, unit, minUnit, max);
    }

    private static void validateQuantity(String value, double quantity, DataRateUnit unit, DataRateUnit minUnit, long max)
    {
        // negatives are not allowed by the regex pattern
        if (minUnit.convert(quantity, unit) >= max)
            throw new IllegalArgumentException("Invalid data rate: " + value + ". It shouldn't be more than " +
                                             (max - 1) + " in " + toLowerCaseLocalized(minUnit.name()));
    }

    private static void validateQuantity(double quantity, DataRateUnit unit, DataRateUnit minUnit, long max)
    {
        if (quantity < 0)
            throw new IllegalArgumentException("Invalid data rate: value must be non-negative");

        if (minUnit.convert(quantity, unit) >= max)
            throw new IllegalArgumentException(String.format("Invalid data rate: %s %s. It shouldn't be more than %d in %s",
                                                       quantity, toLowerCaseLocalized(unit.name()),
                                                       max - 1, toLowerCaseLocalized(minUnit.name())));
    }

    // get vs no-get prefix is not consistent in the code base, but for classes involved with config parsing, it is
    // imporant to be explicit about get/set as this changes how parsing is done; this class is a data-type, so is
    // not nested, having get/set can confuse parsing thinking this is a nested type
    /**

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Lower the rate value so that its conversion to the minimum unit is below the printed max (max-1)
Recheck the unit: a large number in B/s may fit while the same number in MiB/s overflows
Read the exception text — it states the exact maximum allowed in the minimum unit
If the intent is truly unlimited throughput, use a realistic bounded value rather than a sentinel huge number

Example fix

# before
stream_throughput_outbound_rate: 999999999999MiB/s
# after
stream_throughput_outbound_rate: 4000MiB/s

Defensive patterns

Strategy: validation

Validate before calling

long maxAllowed = MAX - 1; // per minUnit from the error message
if (quantityInMinUnit >= maxAllowed)
    throw new IllegalArgumentException("Rate too large; must be < " + maxAllowed);

Try / catch

try {
    rate = DataRateSpec.parseYamlType(value);
} catch (IllegalArgumentException e) {
    logger.error("Data rate out of range: " + value, e);
    rate = DataRateSpec.parseYamlType(DEFAULT_RATE);
}

Prevention

Convert to the smallest unit before comparing against limits
Avoid sentinel huge values to mean 'unlimited'
Keep production rates well inside the documented bounds

When it happens

Trigger: Setting a data rate config value (string form) whose quantity converts to a value >= max in the min unit, e.g. an absurdly large rate like 999999999999MiB/s in cassandra.yaml.

Common situations: Misreading units: entering a huge MiB/s value intending bytes/s; fat-fingering extra digits; template generation with unbounded variables; benchmark configs pushing rates past the long-bound guard.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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