apache/cassandra · error · IllegalArgumentException

You need to run primary range repair on all nodes in the clu

Error message

You need to run primary range repair on all nodes in the cluster.

What it means

RepairOption.parse enforces that primary-range repair cannot be scoped to a subset of nodes or (outside local-DC-only mode) a subset of datacenters. Primary range repair relies on every node owning its primary ranges, so restricting the node set would leave ranges unrepaired. IllegalArgumentException is thrown to prevent a partially-executed primary range repair.

Source

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

            while (tokenizer.hasMoreTokens())
            {
                columnFamilies.add(tokenizer.nextToken().trim());
            }
            option.getColumnFamilies().addAll(columnFamilies);
        }

        // 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;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Run primary range repair without -hosts/-dc restrictions on every node of the cluster
Drop -pr and use a normal (sequential/parallel) repair with your scoping flags
If scope must be local, use the local-DC-only option so primary-range + -dc is accepted

Example fix

// before
nodetool repair -pr -hosts 10.0.0.1 keyspace1
// after
# run on each node:
nodetool repair -pr keyspace1

Defensive patterns

Strategy: validation

Validate before calling

boolean primaryRange = opts.containsKey("primaryRange");
boolean scoped = nonEmpty(opts.get("hosts")) || nonEmpty(opts.get("datacenters"));
if (primaryRange && scoped) throw new IllegalArgumentException("-pr cannot be combined with -hosts/-dc");

Try / catch

try { RepairOption.parse(opts); } catch (IllegalArgumentException e) { if (e.getMessage().contains("primary range repair on all nodes")) { /* rerun unscoped on every node */ } else throw e; }

Prevention

Run -pr repairs as a cluster-wide loop (once per node, unscoped)
Use non-primary-range repair when you need node/DC scoping
Use local-DC-only mode if you must combine primary range with DC scoping

When it happens

Trigger: nodetool repair -pr -hosts h1,h2 ... or -pr with -dc when option.isInLocalDCOnly() is false.

Common situations: Operators assuming -pr can be combined with -hosts to repair 'just this node's primary range'; DC-scoped primary repairs attempted across multi-DC clusters without local-DC-only semantics.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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