apache/cassandra · error · IllegalArgumentException

retries must be non-negative

Error message

retries must be non-negative (retries=${value} supplied)

What it means

When parsing a 'retries=<n>' modifier, RetryStrategy.parse() rejects negative values because a negative retry count is meaningless (it would permit fewer than zero retries). An IllegalArgumentException carrying the supplied value is thrown.

Solutions

1. Change the retries value to a non-negative integer
2. To express unlimited retries, omit the modifier (default is Integer.MAX_VALUE retries)
3. If a negative sentinel was intended as 'disabled', use retries=0 instead

Example fix

// before
RetryStrategy.parse("100ms,retries=-1", latencies);
// after
RetryStrategy.parse("100ms,retries=0", latencies); // or omit retries for unlimited

static int validateRetries(String value) {
    int retries = Integer.parseInt(value.trim());
    if (retries < 0) throw new IllegalArgumentException("retries must be >= 0, got " + value);
    return retries;
}

try {
    RetryStrategy strategy = RetryStrategy.parse(spec, latencies);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("retries must be non-negative")) {
        LOG.warn("Negative retries in spec '{}', falling back to default", spec);
        return RetryStrategy.parse("100ms", latencies);
    }
    throw e;
}

When it happens

Trigger: RetryStrategy.parse(spec, latencies) where spec ends with ',retries=-1' (or any negative integer). The value must parse as an int >= 0.

Common situations: Hand-written config where a negative default like retries=-1 was intended to mean 'unlimited' (use retries=0 or omit the modifier instead); templated config injecting -1 placeholders.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Must permit at least one attempt
• Commit log position must be given as
• could not parse update query
• does not end in unit
• does not match

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

Appendix: source

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

        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;
            }
            if (end != spec.length())
                spec = spec.substring(0, end);
        }

View on GitHub (pinned to 88fd0f6a0e)