apache/cassandra · error · IllegalArgumentException

Tokens must be provided to force join a node.

Error message

Tokens must be provided to force join a node.

What it means

Thrown by ForceJoin when there is no in-progress join sequence for the node and no tokens were supplied. The UnsafeJoin transformation requires an explicit token set to place the node in the ring, so an empty token set is a missing-required-argument error.

Source

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

                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);
        }
    }

    /**
     * Prints the full {@code toString()} representation of the cluster metadata to stdout.
     * Useful for a quick human-readable overview of the entire metadata state.
     * <p>
     * <b>Note:</b> The output format is not stable and may change between versions.
     * Do not rely on it for programmatic parsing.
     */
    @Command(name = "print", description = "Prints string output of the cluster metadata. " +
                                           "Output format is subject to change and should not be relied on for parsing.")

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Provide the token list with --tokens <t1,t2,...> for the node.
  2. Generate appropriate tokens (e.g. with GenerateTokens or the cluster's allocation strategy such as UniformRangePlacement semantics).
  3. If the node has a pending join sequence, omit tokens to resume it instead.

Example fix

// before
// cms offline force-join --id 3
// after
// cms offline force-join --id 3 --tokens -9223372036854775808,0,3074457345618258602
Defensive patterns

Strategy: validation

Validate before calling

if (metadata.inProgressSequences.get(nodeId) == null && tokenSet.isEmpty())
    throw new IllegalArgumentException("--tokens is required when no join sequence is in progress");

Try / catch

try { forceJoin(...); } catch (IllegalArgumentException e) { System.err.println("Supply --tokens: " + e.getMessage()); }

Prevention

When it happens

Trigger: Running force join for a node with no inProgressSequences entry and without the --tokens option, so tokenSet is empty when constructing UnsafeJoin.

Common situations: First-time force join of a failed bootstrap where the operator forgets that tokens are mandatory; scripts that pass tokens only in some branches; confusing this tool with online CMS commands that can allocate tokens automatically.

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

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