apache/cassandra · error · java.lang.IllegalArgumentException

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

Error message

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

What it means

validateQuantity rejects durations that, converted to the spec's minimum unit, reach or exceed the configured upper bound (max). The message reports the largest allowed value (max-1) in the min unit. This bounds duration-typed config properties to prevent unbounded/extreme values.

Source

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

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

    private static String acceptedUnits(TimeUnit minUnit)
    {
        TimeUnit[] units = TimeUnit.values();
        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()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Reduce the value below the printed maximum (max-1) in the shown unit
  2. Convert to a larger unit if appropriate (e.g. 720h instead of huge ms numbers)
  3. Check the spec's javadoc/source for the intended maximum for that property
  4. If a 'disabled' semantic is needed, use the property's documented disable value (often 0 or -1) instead of a huge duration

Example fix

// before (max 30 days)
guardrail_window = "3650d";
// after
guardrail_window = "29d";
Defensive patterns

Strategy: validation

Validate before calling

static void checkMax(String v, long maxInMinUnit, TimeUnit minUnit) {
    long qty = Long.parseLong(v.replaceAll("[a-zµ]+$", ""));
    TimeUnit u = symbolToEnum(v.replaceAll("^\\d+", ""));
    if (minUnit.convert(qty, u) >= maxInMinUnit)
        throw new IllegalArgumentException("Duration exceeds cap: " + v);
}

Try / catch

try {
    spec = new MyDurationSpec("3650d");
} catch (IllegalArgumentException e) {
    logger.error("Duration over max: {}", e.getMessage());
}

Prevention

When it happens

Trigger: Setting a duration property to a value that overflows the spec's maximum, e.g. '3650d' on a spec capped at 30 days, or a huge value in ms like '999999999999ms'.

Common situations: Disabling-style attempts with extremely large durations; misreading the unit so '30d' becomes 30 days when ms was intended; copy-pasting values from other systems with different caps.

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