apache/cassandra · error · IllegalArgumentException

Invalid data storage: value must be non-negative

Error message

Invalid data storage: value must be non-negative

What it means

The programmatic (long-based) constructor of DataStorageSpec rejects negative quantities, since storage sizes cannot be negative. Unlike the string parser, which guards this via regex, the numeric constructor validates explicitly and throws IllegalArgumentException.

Source

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

    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
    /**
     * @return the data storage quantity.
     */
    public long quantity()
    {
        return quantity;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Fix the computation so the quantity is never negative
  2. Clamp the value with Math.max(0, quantity) before constructing the spec
  3. Check sentinel defaults (e.g. -1 meaning unset) and substitute a real value before passing it

Example fix

// before
DataStorageSpec.DataStorageBytesBound bound = new DataStorageSpec.DataStorageBytesBound(freeBytes);
// after
if (freeBytes < 0) throw new IllegalStateException("computed negative size: " + freeBytes);
DataStorageSpec.DataStorageBytesBound bound = new DataStorageSpec.DataStorageBytesBound(Math.max(0, freeBytes));
Defensive patterns

Strategy: validation

Validate before calling

if (quantity < 0) throw new IllegalArgumentException("size must be >= 0, got " + quantity);

Try / catch

try { new DataStorageSpec.DataStorageBytesBound(size); } catch (IllegalArgumentException e) { /* fall back to default */ }

Prevention

When it happens

Trigger: Calling new DataStorageSpec.DataStorageBytesBound(-1024) (or any long-based DataStorageSpec constructor) with a negative value, typically from code that computes a size programmatically.

Common situations: Bugs in code that derives storage sizes from subtraction (e.g. remaining = total - used going negative), or uninitialized/default sentinel values like -1 being passed as a size.

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