apache/cassandra · error · IllegalArgumentException

Invalid modifier specification: unrecognised property

Error message

Invalid modifier specification: unrecognised property '${key}'

What it means

RetryStrategy.parse() accepts comma-separated trailing modifiers of the form key=value (retries, attempts, rnd). If the key before '=' in a modifier is not one of these, an IllegalArgumentException is thrown with the offending key name. The library throws early so that an invalid retry policy spec never silently produces a strategy with ignored settings.

Solutions

Rename the modifier key to one of the supported values: retries, attempts, or rnd
Check for typos in the key name (e.g. 'retry' -> 'retries')
If using 'maxRetries'-style keys, convert to 'retries=<n>' syntax
Verify the full spec string has no stray segments after the wait definition that look like modifiers

Example fix

// before
RetryStrategy.parse("100ms,maxRetries=5", latencies);
// after
RetryStrategy.parse("100ms,retries=5", latencies);

Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> ALLOWED_KEYS = Set.of("retries", "attempts", "rnd");
static void validateModifiers(String spec) {
    String[] parts = spec.split(",");
    for (int i = 1; i < parts.length; i++) {
        int eq = parts[i].indexOf('=');
        if (eq < 0) throw new IllegalArgumentException("Modifier '" + parts[i] + "' needs '='");
        String key = parts[i].substring(0, eq).trim();
        if (!ALLOWED_KEYS.contains(key))
            throw new IllegalArgumentException("Unknown modifier key: " + key);
    }
}

Try / catch

try {
    RetryStrategy strategy = RetryStrategy.parse(spec, latencies);
} catch (IllegalArgumentException e) {
    LOG.error("Invalid retry spec '{}': {}", spec, e.getMessage());
    throw new ConfigurationException("Bad retry strategy spec: " + spec, e);
}

Prevention

Only use retries, attempts, or rnd as modifier keys
Validate specs at config-load time, not at first request time
Keep retry specs in one shared constant/builder instead of inline strings

When it happens

Trigger: Calling RetryStrategy.parse(spec, latencies) where a trailing ',<key>=<value>' modifier uses an unknown key, e.g. "100ms,retry=5" or "500ms,maattempt=3" (typo). The modifier parser splits on the last ',' and expects key in {retries, attempts, rnd}.

Common situations: Typos in cassandra.yaml or programmatically built retry specs; copying spec syntax from another library with different modifier names (e.g. 'maxRetries' instead of 'retries'); config drift after a version change renaming accepted keys.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/RetryStrategy.java:280

    }

    public static RetryStrategy parse(String spec, LatencySourceFactory latencies, WaitRandomizer randomizer)
    {
        String original = spec;
        int retries = Integer.MAX_VALUE;
        int end = spec.length();
        {
            int next;
            while ((next = spec.lastIndexOf(',', end - 1)) >= 0)
            {
                int mid = spec.indexOf('=', next + 1);
                if (mid <= next || mid >= end)
                    throw new IllegalArgumentException("Invalid modifier specification: '" + spec.substring(next, end) + "'; expecting '=' for value assignment");
                String key = spec.substring(next + 1, mid).trim();
                String value = spec.substring(mid + 1, end).trim();
                switch (key)
                {
                    default: throw new IllegalArgumentException("Invalid modifier specification: unrecognised property '" + key + '\'');
                    case "retries":
                        retries = Integer.parseInt(value);
                        if (retries < 0)
                            throw new IllegalArgumentException("retries must be non-negative (retries=" + value + " supplied)");
                        break;
                    case "attempts":
                        retries = Integer.parseInt(value);
                        if (retries < 0)
                            throw new IllegalArgumentException("Must permit at least one attempt (attempts=" + value + " supplied)");
                        break;
                    case "rnd":
                        if (randomizer != null)
                            throw new IllegalArgumentException("Randomizer already specified, cannot re-specify: " + value);
                        randomizer = parseWaitRandomizer(value);
                        break;
                }
                end = next;
            }

View on GitHub (pinned to 88fd0f6a0e)