apache/cassandra · warning

manually specified tokens override automatic allocation

Error message

manually specified tokens override automatic allocation

What it means

BootStrapper.getBootstrapTokens warns that manually configured initial_token values take precedence over automatic token allocation (allocate_tokens_for_local_replication_factor or allocate_tokens_for_keyspace). When both are set, the explicit tokens win and the automatic allocation is skipped, which can silently break the intended even-distribution strategy.

Source

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

                ProgressEvent currentProgress = new ProgressEvent(ProgressEventType.ERROR, receivedFiles.get(), totalFilesToReceive.get(), throwable.getMessage());
                fireProgressEvent("bootstrap", currentProgress);
            }
        });
        return bootstrapStreamResult;
    }

    /**
     * if initialtoken was specified, use that (split on comma).
     * otherwise, if allocationKeyspace is specified use the token allocation algorithm to generate suitable tokens
     * else choose num_tokens tokens at random
     */
    public static Collection<Token> getBootstrapTokens(final ClusterMetadata metadata, InetAddressAndPort address) throws ConfigurationException
    {
        String allocationKeyspace = DatabaseDescriptor.getAllocateTokensForKeyspace();
        Integer allocationLocalRf = DatabaseDescriptor.getAllocateTokensForLocalRf();
        Collection<String> initialTokens = DatabaseDescriptor.getInitialTokens();
        if (initialTokens.size() > 0 && allocationKeyspace != null)
            logger.warn("manually specified tokens override automatic allocation");

        // if user specified tokens, use those
        if (initialTokens.size() > 0)
        {
            Collection<Token> tokens = getSpecifiedTokens(metadata, initialTokens);
            BootstrapDiagnostics.useSpecifiedTokens(address, allocationKeyspace, tokens, DatabaseDescriptor.getNumTokens());
            return tokens;
        }

        int numTokens = DatabaseDescriptor.getNumTokens();
        if (numTokens < 1)
            throw new ConfigurationException("num_tokens must be >= 1");

        if (allocationKeyspace != null)
            return allocateTokens(metadata, address, allocationKeyspace, numTokens);

        if (allocationLocalRf != null)
            return allocateTokens(metadata, address, allocationLocalRf, numTokens);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove initial_token / initial_tokens from cassandra.yaml if you want automatic allocation to be used.
2. Remove allocate_tokens_for_keyspace / allocate_tokens_for_local_replication_factor if you intend to keep the manually specified tokens.
3. Verify the resulting token ownership after bootstrap (nodetool ring / nodetool describering) matches your intent.

Example fix

// before (cassandra.yaml)
initial_token: -9223372036854775808
allocate_tokens_for_local_replication_factor: 3
// after (choose one strategy)
# initial_token removed so automatic allocation is honored
allocate_tokens_for_local_replication_factor: 3

# Before bootstrap, verify only ONE token strategy is configured
grep -E '^(initial_token|allocate_tokens_for_local_replication_factor|allocate_tokens_for_keyspace):' /etc/cassandra/cassandra.yaml
# Fail if both initial_token and allocate_tokens_* are set

When it happens

Trigger: Node bootstrap with both initial_token(s) set in cassandra.yaml and allocate_tokens_for_keyspace or allocate_tokens_for_local_replication_factor configured.

Common situations: Operator copies a cassandra.yaml template that sets initial_token while also enabling RF-based allocation; migrating a cluster where old nodes had explicit tokens and new config added allocation settings.

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

• num_tokens must be >= 1
• Problem opening token allocation keyspace " + allocationKeys
• Load CIDR groups cache operation not supported by %s
• Unsupported parameter '%s' for %s, supported parameters are
• JAAS login configuration missing for JMX authenticator setup

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