apache/cassandra · error · IllegalArgumentException

Token ranges must be specified when performing pull repair.

Error message

Token ranges must be specified when performing pull repair. Please specify at least one token range which both hosts have in common.

What it means

Pull repair streams only explicit token ranges, so RepairOption.parse requires at least one range when --pull is used. With no ranges supplied there is nothing to pull and the request is rejected with IllegalArgumentException.

Source

Thrown at src/java/org/apache/cassandra/repair/messages/RepairOption.java:301

            throw new IllegalArgumentException("Too many job threads. Max is " + MAX_JOB_THREADS);
        }
        if (!dataCenters.isEmpty() && !hosts.isEmpty())
        {
            throw new IllegalArgumentException("Cannot combine -dc and -hosts options.");
        }
        if (primaryRange && ((!dataCenters.isEmpty() && !option.isInLocalDCOnly()) || !hosts.isEmpty()))
        {
            throw new IllegalArgumentException("You need to run primary range repair on all nodes in the cluster.");
        }
        if (pullRepair)
        {
            if (hosts.size() != 2)
            {
                throw new IllegalArgumentException("Pull repair can only be performed between two hosts. Please specify two hosts, one of which must be this host.");
            }
            else if (ranges.isEmpty())
            {
                throw new IllegalArgumentException("Token ranges must be specified when performing pull repair. Please specify at least one token range which both hosts have in common.");
            }
        }

        return option;
    }

    private final RepairParallelism parallelism;
    private final boolean primaryRange;
    private final boolean incremental;
    private final boolean trace;
    private final int jobThreads;
    private final boolean pullRepair;
    private final boolean forceRepair;
    private final PreviewKind previewKind;
    private final boolean optimiseStreams;
    private final boolean ignoreUnreplicatedKeyspaces;
    private final boolean repairData;
    private final boolean repairPaxos;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add at least one common token range via -st/-et pairs shared by both hosts
2. Compute ranges from the ring (e.g. nodetool ring / describering) and pass the overlapping ones
3. Drop --pull and use a standard repair if you want full-range repair

Example fix

// before
nodetool repair --pull -hosts 10.0.0.1,10.0.0.2 keyspace1
// after
nodetool repair --pull -hosts 10.0.0.1,10.0.0.2 -st -9223372036854775808 -et -3074457345618258602 keyspace1

if (pullRepair && (ranges == null || ranges.isEmpty()))
    throw new IllegalArgumentException("pull repair requires at least one token range (-st/-et)");

try { RepairOption.parse(opts); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Token ranges must be specified")) { /* derive ranges from ring and retry */ } else throw e; }

When it happens

Trigger: nodetool repair --pull -hosts h1,h2 without any -st/-et (start/end token) range arguments, leaving the ranges list empty.

Common situations: Operators forgetting that pull repair is range-based (unlike normal repair which can repair everything); automation building pull-repair commands that drop empty range args.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Cannot specify a repair as both paxos only and accord only
• Too many job threads. Max is %s
• Cannot combine -dc and -hosts options.
• You need to run primary range repair on all nodes in the clu
• Pull repair can only be performed between two hosts. Please

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