apache/cassandra · error · IllegalArgumentException

The tokens provided ${tokens} do not match with in progress

Error message

The tokens provided ${tokens} do not match with  in progress BootstrapAndJoin sequence tokens ${sequenceTokens}. Cannot proceed further.

What it means

Thrown by ForceJoin when tokens are explicitly provided but do not equal the tokens recorded in the node's in-progress BootstrapAndJoin sequence (bootstrapAndJoin.finishJoin.tokens). The force join must finish the existing sequence with its own tokens, so mismatched user-supplied tokens are rejected.

Source

Thrown at src/java/org/apache/cassandra/tools/CMSOfflineTool.java:677

            {
                MultiStepOperation<?> multiStepOperation = metadata.inProgressSequences.get(nodeId);
                if (multiStepOperation.kind() != MultiStepOperation.Kind.JOIN)
                {
                    throw new IllegalArgumentException("Another sequence of kind " + multiStepOperation.kind() +
                                                       " is in progress for node " + nodeIdentifierOption.getNodeIpOrId() +
                                                       ". Cannot proceed with force join.");
                }
                BootstrapAndJoin bootstrapAndJoin = (BootstrapAndJoin) multiStepOperation;
                Set<Token> sequenceTokens = bootstrapAndJoin.finishJoin.tokens;
                if (tokens.isEmpty()
                    || (tokenSet.size() == sequenceTokens.size() && sequenceTokens.containsAll(tokenSet)))
                {
                    updatedMetadata = bootstrapAndJoin.applyTo(metadata).success().metadata;
                }
                else
                {
                    // If tokens are provided, then it should match with the in-progress sequence tokens
                    throw new IllegalArgumentException("The tokens provided " + tokens + " do not match with " +
                                                       " in progress BootstrapAndJoin sequence tokens " +
                                                       sequenceTokens + ". Cannot proceed further.");
                }
            }
            else
            {
                // There are no in-progress sequences, force join by using UnsafeJoin transformation
                if (tokenSet.isEmpty())
                {
                    throw new IllegalArgumentException("Tokens must be provided to force join a node.");
                }
                UnsafeJoin unsafeJoin = new UnsafeJoin(nodeId, tokenSet, new UniformRangePlacement());
                updatedMetadata = unsafeJoin.execute(metadata).success().metadata;
            }

            writeMetadata(output, updatedMetadata, outputFilePath);
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Omit --tokens so the tool accepts the in-progress sequence's tokens (the empty-tokens path applies the sequence).
  2. Read the exact tokens from the in-progress BootstrapAndJoin sequence and pass them verbatim.
  3. Re-check the metadata snapshot; regenerate tokens only if no sequence is in progress.

Example fix

// before
// forceJoin --id 3 --tokens 100,200   (sequence has [100,200,300])
// after
// forceJoin --id 3                    (no tokens; finishes the pending sequence)
Defensive patterns

Strategy: validation

Validate before calling

Set<Token> sequenceTokens = ((BootstrapAndJoin) metadata.inProgressSequences.get(nodeId)).finishJoin.tokens;
if (!tokens.isEmpty() && !sequenceTokens.equals(tokenSet))
    throw new IllegalArgumentException("Tokens must match the in-progress sequence or be omitted");

Try / catch

try { forceJoin(...); } catch (IllegalArgumentException e) { logger.error("Token mismatch: " + e.getMessage()); }

Prevention

When it happens

Trigger: Passing --tokens to force join while the node has an in-progress BootstrapAndJoin whose token list differs from the provided set (different count, values, or order-insensitive mismatch).

Common situations: Operator guesses or recomputes tokens instead of reading the pending sequence's tokens; copying tokens from another node; re-running the command with tokens from an older attempt after the ring changed.

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

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