apache/cassandra · error · java.lang.IllegalArgumentException

Invalid duration: %d %s. It shouldn't be more than %d in %s

Error message

Invalid duration: %d %s. It shouldn't be more than %d in %s

What it means

The numeric validateQuantity overload also enforces an upper bound: if the quantity converted to minUnit is >= max, an IllegalArgumentException reports the offending value and the maximum allowed (max-1). This is the programmatic (non-string) counterpart of error 313.

Source

Thrown at src/java/org/apache/cassandra/config/DurationSpec.java:123

        return Arrays.toString(Arrays.copyOfRange(units, minUnit.ordinal(), units.length));
    }

    private static void validateQuantity(String value, long quantity, TimeUnit sourceUnit, TimeUnit 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 duration: " + value + ". It shouldn't be more than " +
                                             (max - 1) + " in " + toLowerCaseLocalized(minUnit.name()));
    }

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

        if (minUnit.convert(quantity, sourceUnit) >= max)
            throw new IllegalArgumentException(String.format("Invalid duration: %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
    public long quantity()
    {
        return quantity;
    }

    public TimeUnit unit()
    {
        return unit;
    }

    public Duration toDuration()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Lower the quantity below max-1, or express it in a larger unit
  2. Verify the TimeUnit argument matches the intended semantics of the number
  3. Consult the spec class constant defining max for the allowed ceiling

Example fix

// before (max ~30 days)
new HintedHandoffManagerSpec(100000, TimeUnit.DAYS);
// after
new HintedHandoffManagerSpec(29, TimeUnit.DAYS);
Defensive patterns

Strategy: validation

Validate before calling

static void checkNumericMax(long qty, TimeUnit unit, TimeUnit minUnit, long max) {
    if (minUnit.convert(qty, unit) >= max)
        throw new IllegalArgumentException("Quantity exceeds cap of " + (max - 1));
}

Try / catch

try {
    spec = new MyDurationSpec(amount, unit);
} catch (IllegalArgumentException e) {
    logger.error("Duration out of range: {}", e.getMessage());
}

Prevention

When it happens

Trigger: Constructing a DurationSpec subclass with a long quantity that exceeds the class's max in the given TimeUnit, e.g. new SomeDurationSpec(100_000, TimeUnit.DAYS).

Common situations: Unit mix-ups when passing raw longs (passing milliseconds where days expected); test fixtures with inflated values; computing a duration that overflows the spec's cap.

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