apache/cassandra · error · IllegalArgumentException

Too many job threads. Max is %s

Error message

Too many job threads. Max is %s

What it means

RepairOption.parse validates repair options supplied via nodetool/JMX and refuses a repair request whose parallelism (job threads) exceeds the configured maximum, MAX_JOB_THREADS. IllegalArgumentException is thrown because the request itself is malformed — more parallel repair jobs were requested than Cassandra will ever run. It fails fast before any repair session is created.

Source

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

        }

        // columnfamilies
        String cfStr = options.get(COLUMNFAMILIES_KEY);
        if (cfStr != null)
        {
            Collection<String> columnFamilies = new HashSet<>();
            StringTokenizer tokenizer = new StringTokenizer(cfStr, ",");
            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.");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Lower --job-threads to a value <= MAX_JOB_THREADS (check the constant in RepairOption.java for your version)
2. Remove the --job-threads flag entirely to use the default parallelism
3. Clamp the value in your automation before invoking repair

Example fix

// before
nodetool repair --job-threads 64 keyspace1
// after
nodetool repair --job-threads 4 keyspace1

int jobThreads = Integer.parseInt(opts.getOrDefault("jobThreads", "1"));
if (jobThreads > MAX_JOB_THREADS) throw new IllegalArgumentException("jobThreads must be <= " + MAX_JOB_THREADS);

try { RepairOption.parse(opts); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Too many job threads")) { /* clamp jobThreads and retry */ } else throw e; }

When it happens

Trigger: Calling nodetool repair --job-threads N (or invoking RepairOption.parse programmatically) with N greater than MAX_JOB_THREADS.

Common situations: Operators copying job-thread counts from other clusters or docs, assuming higher parallelism speeds repair; scripts parameterizing job-threads without clamping to the max; version drift where the caller assumes an older, larger limit.

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

• Cannot specify a repair as both paxos only and accord only
• 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
• Token ranges must be specified when performing pull repair.

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