apache/cassandra · error · ConfigurationException

Bootstrapping to existing token " + tokenString + " is not…

Error message

Bootstrapping to existing token " + tokenString + " is not allowed (decommission/removenode the old node first).

What it means

When initial tokens are manually specified (initial_token in cassandra.yaml), getSpecifiedTokens checks the token ring: if another node already owns the requested token, bootstrapping would duplicate ownership, so ConfigurationException is thrown telling the operator to decommission or removenode the old owner first.

Solutions

Run nodetool removenode <host_id> for the node that owns the token (or decommission it) before bootstrapping with that token.
Choose a different, unowned initial_token value for the new node.
If the old node died irrecoverably, use removenode with its host id (found via nodetool status) to purge its tokens.
Remove initial_token entirely and let the allocator pick free tokens automatically.
For node replacement, follow the replace-address workflow (cassandra.replace_address_first_boot) instead of reusing initial_token.

Example fix

// cassandra.yaml before (token already owned)
initial_token: -9223372036854775808
// after
initial_token:  # empty -> auto-allocate unowned tokens

Defensive patterns

Strategy: validation

Validate before calling

// Before bootstrapping with initial_token
Token t = metadata.tokenMap.partitioner().getTokenFactory().fromString(initialToken);
if (metadata.tokenMap.owner(t) != null)
    throw new IllegalStateException("Token already owned by " + metadata.tokenMap.owner(t));

Try / catch

try { node.bootstrap(); }
catch (ConfigurationException e) {
    if (e.getMessage().contains("Bootstrapping to existing token"))
        // removenode the old owner or pick a fresh token
}

Prevention

Always run nodetool removenode before re-adding a node's token
Never copy initial_token between nodes in cassandra.yaml
Prefer auto token allocation over manual initial_token
Use replace_address workflow for node replacement instead of token reuse

When it happens

Trigger: Bootstrap with initial_token containing a token already owned by an existing node in metadata.tokenMap; re-adding a node with its old initial_token after it was replaced without removing the old ownership; cloning a node's cassandra.yaml without changing initial_token.

Common situations: Node replacement workflows where removenode was skipped; copying config between nodes; resurrecting a failed node into a cluster that already reassigned its tokens; test clusters cloned from snapshots.

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/1fd685271d186015. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/dht/BootStrapper.java:264

        if (numTokens == 1)
            logger.warn("Picking random token for a single vnode.  You should probably add more vnodes and/or use the automatic token allocation mechanism.");

        Collection<Token> tokens = getRandomTokens(metadata, numTokens);
        BootstrapDiagnostics.useRandomTokens(address, metadata, numTokens, tokens);
        return tokens;
    }

    private static Collection<Token> getSpecifiedTokens(final ClusterMetadata metadata,
                                                        Collection<String> initialTokens)
    {
        logger.info("tokens manually specified as {}",  initialTokens);
        List<Token> tokens = new ArrayList<>(initialTokens.size());
        for (String tokenString : initialTokens)
        {
            Token token = metadata.tokenMap.partitioner().getTokenFactory().fromString(tokenString);
            if (metadata.tokenMap.owner(token) != null)
                throw new ConfigurationException("Bootstrapping to existing token " + tokenString + " is not allowed (decommission/removenode the old node first).");
            tokens.add(token);
        }
        return tokens;
    }

    static Collection<Token> allocateTokens(final ClusterMetadata metadata,
                                            InetAddressAndPort address,
                                            String allocationKeyspace,
                                            int numTokens)
    {
        Keyspace ks = Keyspace.open(allocationKeyspace);
        if (ks == null)
            throw new ConfigurationException("Problem opening token allocation keyspace " + allocationKeyspace);
        AbstractReplicationStrategy rs = ks.getReplicationStrategy();

        Collection<Token> tokens = TokenAllocation.allocateTokens(metadata, rs, address, numTokens);
        BootstrapDiagnostics.tokensAllocated(address, metadata, allocationKeyspace, numTokens, tokens);
        return tokens;

View on GitHub (pinned to 88fd0f6a0e)