apache/cassandra · error · java.lang.IllegalArgumentException

Unsupported time unit: %s. Supported units are: %s

Error message

Unsupported time unit: %s. Supported units are: %s

What it means

IllegalArgumentException from DurationSpec.fromSymbol: the given unit symbol did not match any supported time-unit suffix (d, h, m, s, ms, us/µs, ns — matched case-insensitively). It is the terminal guard of the symbol switch and fires when parsing a duration string's unit portion anywhere a DurationSpec is constructed.

Source

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

    /**
     * @param symbol the time unit symbol
     * @return the time unit associated to the specified symbol
     */
    public static TimeUnit fromSymbol(String symbol)
    {
        switch (toLowerCaseLocalized(symbol))
        {
            case "d": return DAYS;
            case "h": return HOURS;
            case "m": return MINUTES;
            case "s": return SECONDS;
            case "ms": return MILLISECONDS;
            case "us":
            case "µs": return MICROSECONDS;
            case "ns": return TimeUnit.NANOSECONDS;
        }
        throw new IllegalArgumentException(String.format("Unsupported time unit: %s. Supported units are: %s",
                                                       symbol, Arrays.stream(TimeUnit.values())
                                                                     .map(DurationSpec::symbol)
                                                                     .collect(Collectors.joining(", "))));
    }

    /**
     * @param targetUnit the time unit
     * @return this duration in the specified time unit
     */
    public long to(TimeUnit targetUnit)
    {
        return targetUnit.convert(quantity, unit);
    }

    @Override
    public int hashCode()
    {
        // Milliseconds seems to be a reasonable tradeoff

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use one of the supported symbols exactly: d, h, m, s, ms, us, µs, ns
2. Convert unsupported units (e.g. 1w -> 7d)
3. Ensure lowercase ASCII 'us' if the micro symbol is problematic

Example fix

// before
 retention = "4w";
// after
 retention = "28d";

private static final Set<String> UNITS = Set.of("d","h","m","s","ms","us","µs","ns");
static void checkUnit(String v) {
    String unit = v.replaceAll("^\\d+", "");
    if (!UNITS.contains(unit)) throw new IllegalArgumentException("Unsupported unit: " + unit);
}

try {
    spec = new MyDurationSpec("4w");
} catch (IllegalArgumentException e) {
    logger.error("Unsupported time unit: {}", e.getMessage());
}

When it happens

Trigger: A duration string whose unit portion fails the switch, e.g. '5w', '5H', '5 min', '5sec', or a multi-byte lookalike for 'µs'.

Common situations: Using units from other ecosystems (w for weeks, m confused with min); uppercase units; unicode issues typing µ.

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

• Invalid value of auto_snapshot_ttl: ${conf.auto_snapshot_ttl
• Invalid duration: %s Accepted units:%s where case matters an
• Invalid duration: value must be non-negative
• The duration months, days and nanoseconds must be all of the
• Max profiling duration is %s seconds. If you need longer pro

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