apache/cassandra · error · IllegalArgumentException

Unknown duration symbol '%s'

Error message

Unknown duration symbol '%s'

What it means

This IllegalArgumentException is thrown by Duration.Parser.add when a lowercase symbol token inside a CQL duration string is not one of the recognized unit symbols (y, mo, w, d, h, m, s, ms, us, ns, etc.). The parser only appends values when the symbol matches a known unit; anything else is rejected. It means the duration literal contains an unrecognized unit abbreviation.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/Duration.java:282

            return builder.addMinutes(number);
        }
        else if (s.equals("s"))
        {
            return builder.addSeconds(number);
        }
        else if (s.equals("ms"))
        {
            return builder.addMillis(number);
        }
        else if (s.equals("us") || s.equals("µs"))
        {
            return builder.addMicros(number);
        }
        else if (s.equals("ns"))
        {
            return builder.addNanos(number);
        }
        throw new IllegalArgumentException(String.format("Unknown duration symbol '%s'", symbol));
    }

    /**
     * Appends the result of the division to the specified builder if the dividend is not zero.
     *
     * @param builder  the builder to append to
     * @param dividend the dividend
     * @param divisor  the divisor
     * @param unit     the time unit to append after the result of the division
     * @return the remainder of the division
     */
    private static long append(StringBuilder builder, long dividend, long divisor, String unit)
    {
        if (dividend == 0 || dividend < divisor) return dividend;

        builder.append(dividend / divisor).append(unit);
        return dividend % divisor;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Fix the duration string to use only recognized symbols: y, mo, w, d, h, m, s, ms, us (or µs), ns
2. Remember 'm' is minutes and 'mo' is months; correct month/minute confusion
3. Wrap Duration.from in try-catch for IllegalArgumentException and surface a user-friendly message listing valid units

Example fix

// before
Duration.from("2hrs 30min")
// after
Duration.from("2h 30m")

private static final Pattern DURATION_UNIT = Pattern.compile("^(\\d+)(y|mo|w|d|h|m|s|ms|us|µs|ns)$");
static boolean isValidDurationToken(String token) { return DURATION_UNIT.matcher(token).matches(); }
// validate each number+unit pair of the duration string before Duration.from

try { Duration d = Duration.from(input); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Invalid duration unit: " + e.getMessage(), e); }

When it happens

Trigger: Calling Duration.from("1yr") or any statement binding a duration literal with an unknown unit suffix; the parser splits the string into number/symbol pairs and hits a symbol not in its switch of recognized units.

Common situations: Typos in duration units ('2mnts', '5hrs'); confusing months ('mo') with minutes ('m'); using units like 'yr', 'sec', 'min' that are valid in human writing but not in the CQL duration grammar; copying durations from other libraries with different unit vocabularies.

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

• Unable to convert '%s' to a duration
• Invalid duration. The %s are specified multiple times
• Invalid duration. The %s should be after %s
• Timestamp format must be hh:mm:ss[.fffffffff]
• Hour out of bounds.

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