apache/cassandra · error · IllegalArgumentException

max attempt must be positive; but given <value>

Error message

max attempt must be positive; but given <value>

What it means

RetrySpec.MaxAttempt is a typed config wrapper enforcing that a retry max-attempt count is at least 1. The constructor throws IllegalArgumentException for any value < 1. It fails fast when YAML or code supplies a zero or negative attempt count.

Source

Thrown at src/java/org/apache/cassandra/config/RetrySpec.java:46

import org.apache.cassandra.repair.SharedContext;
import org.apache.cassandra.service.RetryStrategy;
import org.apache.cassandra.service.TimeoutStrategy.LatencySourceFactory;
import org.apache.cassandra.service.WaitStrategy;

import static org.apache.cassandra.service.RetryStrategy.randomizers;

public class RetrySpec
{
    public static class MaxAttempt
    {
        public static final MaxAttempt DISABLED = new MaxAttempt();

        public final int value;

        public MaxAttempt(int value)
        {
            if (value < 1)
                throw new IllegalArgumentException("max attempt must be positive; but given " + value);
            this.value = value;
        }

        private MaxAttempt()
        {
            value = 0;
        }

        @Override
        public boolean equals(Object o)
        {
            if (this == o) return true;
            if (o == null) return false;
            if (o instanceof Integer) return this.value == ((Integer) o).intValue();
            if (getClass() != o.getClass()) return false;
            MaxAttempt that = (MaxAttempt) o;
            return value == that.value;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set max_attempt to a positive integer (>= 1)
2. If retries should be disabled, use the mechanism intended for disabling rather than 0 attempts
3. Validate any programmatically-built retry spec before passing it in

Example fix

// before
max_attempt: 0
// after
max_attempt: 3

int maxAttempt = parseMaxAttempt(yamlValue);
if (maxAttempt < 1) throw new IllegalArgumentException("max attempt must be positive");

static boolean isValidMaxAttempt(int v) { return v >= 1; }

try { new RetrySpec.MaxAttempt(v); }
catch (IllegalArgumentException e) { log.warn("Falling back to default max attempts"); }

When it happens

Trigger: Configuring a retry spec (e.g. for driver or internal retries) with max_attempt: 0 or a negative integer, in cassandra.yaml or programmatically.

Common situations: Setting max_attempt to 0 intending 'unlimited' or 'disabled'; typo or misread units; template configs copied with placeholder values.

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

• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s
• Invalid value of entire_sstable_stream_throughput_outbound:
• Invalid value of entire_sstable_inter_dc_stream_throughput_o
• %s (%s) must be greater than or equal to %s (%s)

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