apache/cassandra · error · java.lang.IllegalArgumentException

Invalid duration: %s Accepted units:%s

Error message

Invalid duration: %s Accepted units:%s

What it means

validateMinUnit rejects a parsed duration whose unit is finer than the minimum unit permitted for that spec (e.g. a seconds-based spec given '500ms'). The value format was otherwise valid, but the unit granularity is not accepted. Thrown as IllegalArgumentException with the accepted units list.

Source

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

        else
        {
            throw new IllegalArgumentException("Invalid duration: " + value + " Accepted units:" + acceptedUnits(minUnit) +
                                               " where case matters and only non-negative values.");
        }
    }

    private DurationSpec(String value, TimeUnit minUnit, long max)
    {
        this(value, minUnit);

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

    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)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Convert the value to the minimum allowed unit (e.g. 10us -> 0ms is not possible; use a larger value or a coarser unit)
  2. Check the spec class definition to see the minUnit enforced by that property's constructor
  3. Use the smallest allowed unit symbol listed in the error message

Example fix

// before (minUnit ms)
coordinator_write_size = "10us";
// after
coordinator_write_size = "1ms";
Defensive patterns

Strategy: validation

Validate before calling

static void checkMinUnit(String v, TimeUnit minUnit) {
    Matcher m = DURATION.matcher(v.trim());
    if (m.matches() && TimeUnit.valueOf(symbolToEnum(m.group(2))).compareTo(minUnit) < 0)
        throw new IllegalArgumentException("Unit too fine for this spec: " + v);
}

Try / catch

try {
    new MyDurationSpec("10us");
} catch (IllegalArgumentException e) {
    logger.error("Unit below minimum allowed: {}", e.getMessage());
}

Prevention

When it happens

Trigger: Configuring a DurationSpec-typed property whose minUnit is e.g. MILLISECONDS with a value in 'us' or 'ns', such as a property declared with minUnit ms receiving '10us'.

Common situations: Copying a duration value between properties with different minimum units; downsizing timeouts to sub-millisecond precision where the spec disallows it.

Understand the failure class

Background: "invalid duration" / "failed to parse duration": why your timeout, interval, or TTL string is rejected and which formats each library accepts — this error's family across 32 libraries.

Related errors

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