apache/cassandra · error · IllegalArgumentException

Invalid specification

Error message

Invalid specification: '{input}'; does not match {PARSE}

What it means

Thrown by TimeoutStrategy.parse when the whole input string does not match the PARSE regular expression that defines valid timeout strategy specifications. The message includes both the input and the expected pattern.

Solutions

1. Match the input against the PARSE pattern printed in the message and fix the syntax.
2. Use the documented form, e.g. 'min..max for <wait expression>' structure expected by the regex.
3. Simplify to a constant timeout spec and build up complexity until it parses.

Example fix

// before
TimeoutStrategy.parse("100ms", latencies); // missing required structure
// after
TimeoutStrategy.parse("0..1s for fixed(100ms)", latencies);

java.util.regex.Pattern PARSE = java.util.regex.Pattern.compile("<the documented strategy grammar>");
if (!PARSE.matcher(input).matches()) throw new IllegalArgumentException("invalid timeout spec: " + input);

try { TimeoutStrategy.parse(input, latencies); }
catch (IllegalArgumentException e) { if (e.getMessage().contains("Invalid specification")) { /* fix syntax per printed pattern */ } throw e; }

When it happens

Trigger: Passing a malformed strategy string to parse() (used for configurable timeouts), e.g. missing the wait clause, stray characters, or wrong ordering of min/max/wait parts.

Common situations: Typing timeout expressions by hand in cassandra.yaml or system properties; whitespace or punctuation errors; confusing timeout strategy syntax with plain duration strings.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• does not match
• Invalid latency modifier specification
• does not match
• Unrecognised attempt modifier
• is not a parsable long (base10) for

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/TimeoutStrategy.java:345

            return modifiers.multiplyByAttempts(modifier);
        else if (modkind.startsWith("^"))
            return modifiers.multiplyByAttemptsExp(modifier);
        else
            throw new IllegalArgumentException("Unrecognised attempt modifier: " + modkind);
    }

    static long saturatedCast(double v)
    {
        if (v > Long.MAX_VALUE)
            return Long.MAX_VALUE;
        return (long) v;
    }

    public static TimeoutStrategy parse(String input, LatencySourceFactory latencies)
    {
        Matcher m = PARSE.matcher(input);
        if (!m.matches())
            throw new IllegalArgumentException("Invalid specification: '" + input + "'; does not match " + PARSE);
        long min = parseInMicros(m.group("min"), 0);
        long max = parseInMicros(m.group("max"), Long.MAX_VALUE);
        Wait wait = TimeoutStrategy.parseWait(m.group("wait"), latencies);
        return new TimeoutStrategy(wait, min, max);
    }

    public static Wait parseWait(String input, LatencySourceFactory latencies)
    {
        return parseWait(input, latencies, modifiers);
    }

    @VisibleForTesting
    static Wait parseWait(String input, LatencySourceFactory latencies, LatencyModifierFactory modifiers)
    {
        Matcher m = WAIT.matcher(input);
        if (!m.matches())
            throw new IllegalArgumentException(input + " does not match " + WAIT);

View on GitHub (pinned to 88fd0f6a0e)