apache/cassandra · error · IllegalArgumentException

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

Error message

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

What it means

DataStorageSpec parses Cassandra config values with data-storage units (e.g. 512MiB, 1GiB). This error is thrown when a parsed quantity, converted to the minimum allowed unit for that spec, equals or exceeds the maximum bound — the value is simply too large for the setting.

Source

Thrown at src/java/org/apache/cassandra/config/DataStorageSpec.java:103

    private static void validateMinUnit(DataStorageUnit sourceUnit, DataStorageUnit minUnit, String value)
    {
        if (sourceUnit.compareTo(minUnit) < 0)
            throw new IllegalArgumentException(String.format("Invalid data storage: %s Accepted units:%s", value, acceptedUnits(minUnit)));
    }

    private static String acceptedUnits(DataStorageUnit minUnit)
    {
        DataStorageUnit[] units = DataStorageUnit.values();
        return Arrays.toString(Arrays.copyOfRange(units, minUnit.ordinal(), units.length));
    }

    private static void validateQuantity(String value, long quantity, DataStorageUnit sourceUnit, DataStorageUnit minUnit, long max)
    {
        // no need to validate for negatives as they are not allowed at first place from the regex

        if (minUnit.convert(quantity, sourceUnit) >= max)
            throw new IllegalArgumentException("Invalid data storage: " + value + ". It shouldn't be more than " +
                                               (max - 1) + " in " + toLowerCaseLocalized(minUnit.name()));
    }

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

        if (minUnit.convert(quantity, sourceUnit) >= max)
            throw new IllegalArgumentException(String.format("Invalid data storage: %d %s. It shouldn't be more than %d in %s",
                                                             quantity, toLowerCaseLocalized(sourceUnit.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

Reduce the value in cassandra.yaml so it is below the documented maximum for that setting
Use a larger unit to express the same size (e.g. 2GiB instead of 2147483648 bytes) so the numeric literal stays in range
Check for unit confusion: verify the suffix (B, KiB, MiB, GiB) matches what you intend

Example fix

// before (cassandra.yaml)
max_mutation_size_in_kb: 999999999999
// after
max_mutation_size_in_kb: 16384

Defensive patterns

Strategy: validation

Validate before calling

long valueInUnits = unit.convert(quantity, TimeUnit-like source); if (valueInUnits >= MAX_BOUND) throw new IllegalArgumentException(value + " exceeds max " + (MAX_BOUND - 1));

Try / catch

try { new DataStorageSpec.DataStorageBytesBound(confValue); } catch (IllegalArgumentException e) { log.error("bad size config: {}", e.getMessage()); }

Prevention

Keep storage values well below documented maximums
Use the largest sensible unit (MiB/GiB) to avoid huge numerics
Validate cassandra.yaml values in CI with a config parse test

When it happens

Trigger: Constructing a DataStorageSpec subclass (e.g. DataStorageSpec.DataStorageBytesBound) from a string via ConfigParser, or programmatically via the long constructor, where minUnit.convert(quantity, sourceUnit) >= max — e.g. a value that overflows or exceeds Long.MAX_VALUE when normalized.

Common situations: A cassandra.yaml value like max_mutation_size_in_kb set far beyond bounds, pasted example configs with absurd sizes, or unit confusion (entering bytes where MiB was expected, producing a huge number).

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