apache/cassandra · error · java.lang.IllegalArgumentException

Invalid duration: %s Accepted units:%s where case matters an

Error message

Invalid duration: %s Accepted units:%s where case matters and only non-negative values.

What it means

DurationSpec's string constructor parses values like '100ms' with a regex anchored to a set of accepted units (>= minUnit). If the value does not match (bad unit, negative number, whitespace, missing unit), an IllegalArgumentException with the accepted units list is thrown. Case matters: '100MS' or '100Ms' is rejected.

Source

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

    private DurationSpec(double quantity, TimeUnit unit, TimeUnit minUnit, long max)
    {
        this(Math.round(quantity), unit, minUnit, max);
    }

    private DurationSpec(String value, TimeUnit minUnit)
    {
        Matcher matcher = UNITS_PATTERN.matcher(value);

        if (matcher.find())
        {
            quantity = Long.parseLong(matcher.group(1));
            unit = fromSymbol(matcher.group(2));

            // this constructor is used only by extended classes for min unit; upper bound and min unit are guarded there accordingly
        }
        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)));
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Rewrite the value with a correct, lowercase unit symbol (d, h, m, s, ms, us, µs, ns) allowed for that property
Remove signs/whitespace: only non-negative plain numbers plus unit are accepted
Check the property's documentation for its minimum accepted unit
If set programmatically, use the long-valued constructor with the intended TimeUnit instead of a string

Example fix

// before
read_request_timeout = "5000MS";
// after
read_request_timeout = "5000ms";

Defensive patterns

Strategy: validation

Validate before calling

private static final Pattern DURATION = Pattern.compile("^(\\d+)(d|h|m|s|ms|us|µs|ns)$");
static void checkDuration(String v) {
    if (v == null || !DURATION.matcher(v.trim()).matches())
        throw new IllegalArgumentException("Invalid duration: " + v);
}

Try / catch

try {
    config.setReadRequestTimeout("5000ms");
} catch (IllegalArgumentException e) {
    logger.error("Duration config rejected: {}", e.getMessage());
}

Prevention

Always use lowercase unit symbols
Never prefix durations with a sign
Include the unit; never pass a bare number string
Validate durations at config-load time with a regex pre-check

When it happens

Trigger: Setting any duration-typed cassandra.yaml/config property (e.g. read_request_timeout, gc_grace_seconds-like specs) with a value whose unit symbol is unknown, wrong case, negative, malformed, or below the minUnit allowed for that property.

Common situations: Typo in unit ('duries', '100sec'), uppercase units ('100S'), negative durations ('-5s'), missing unit ('100'), or using a unit finer than the property's minimum (e.g. 'ns' where 'ms' is the floor).

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