apache/cassandra · error · IllegalArgumentException

Pull repair can only be performed between two hosts. Please

Error message

Pull repair can only be performed between two hosts. Please specify two hosts, one of which must be this host.

What it means

Pull repair (incremental streaming one direction only) is defined strictly between two hosts. RepairOption.parse throws IllegalArgumentException unless exactly two hosts were supplied — fewer or more than two makes the pull semantics undefined.

Source

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

        // validate options
        if (jobThreads > MAX_JOB_THREADS)
        {
            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;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pass exactly two hosts with -hosts, one of which must be the local node
2. Remove --pull if you actually want a normal multi-host repair
3. Split larger topologies into pairwise pull repairs

Example fix

// before
nodetool repair --pull -hosts 10.0.0.1,10.0.0.2,10.0.0.3 keyspace1
// after
nodetool repair --pull -hosts 10.0.0.1,10.0.0.2 keyspace1

if (pullRepair && (hosts == null || hosts.size() != 2))
    throw new IllegalArgumentException("pull repair requires exactly two hosts");

try { RepairOption.parse(opts); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Pull repair can only be performed between two hosts")) { /* fix host list */ } else throw e; }

When it happens

Trigger: nodetool repair --pull ... with a host list whose size != 2 (0, 1, or 3+ hosts).

Common situations: Operators reusing a generic repair command with many -hosts entries and adding --pull; forgetting that pull repair requires exactly the two endpoints.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 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
• Token ranges must be specified when performing pull repair.

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