apache/cassandra · error · ConfigurationException

initial_token was set but num_tokens is not!

Error message

initial_token was set but num_tokens is not!

What it means

When configuring the token ring (applyInitialToken/NumTokens logic), if initial_token is set but num_tokens is absent, Cassandra infers num_tokens only when exactly one token was given; with multiple initial_tokens it cannot guess the intended vnode count and throws this ConfigurationException. The token count must always match num_tokens.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1750

                    lowestAcceptedValue);
    }

    public static void applyTokensConfig()
    {
        applyTokensConfig(conf);
    }

    static void applyTokensConfig(Config conf)
    {
        if (conf.initial_token != null)
        {
            Collection<String> tokens = tokensFromString(conf.initial_token);
            if (conf.num_tokens == null)
            {
                if (tokens.size() == 1)
                    conf.num_tokens = 1;
                else
                    throw new ConfigurationException("initial_token was set but num_tokens is not!", false);
            }

            if (tokens.size() != conf.num_tokens)
            {
                throw new ConfigurationException(String.format("The number of initial tokens (by initial_token) specified (%s) is different from num_tokens value (%s)",
                                                               tokens.size(),
                                                               conf.num_tokens),
                                                 false);
            }

            for (String token : tokens)
                partitioner.getTokenFactory().validate(token);
        }
        else if (conf.num_tokens == null)
        {
            conf.num_tokens = 1;
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set num_tokens in cassandra.yaml to match the number of values in initial_token
2. Or remove initial_token and let Cassandra auto-assign with the configured num_tokens
3. If you intended a single-token legacy node, keep exactly one token value and num_tokens: 1

Example fix

// cassandra.yaml before
initial_token: tokenA,tokenB,tokenC
// after
num_tokens: 3
initial_token: tokenA,tokenB,tokenC

if (conf.initial_token != null) {
    int n = conf.initial_token.split(",").length;
    if (conf.num_tokens == null ? n != 1 : conf.num_tokens != n)
        throw new IllegalStateException("num_tokens must match initial_token count (" + n + ")");
}

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* align num_tokens with initial_token */ }

When it happens

Trigger: cassandra.yaml defines initial_token (or multiple comma-separated tokens) while num_tokens is omitted, and the number of tokens parsed from initial_token is not exactly 1.

Common situations: Operators migrating from single-token setups (pre-1.2 style) or from 3.x 8-vnode defaults paste old initial_token lines into a config without num_tokens; multi-token manual assignments for balanced clusters after a resize.

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

• A maximum number of %d tokens per node is supported
• num_tokens must be >= 1
• 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/d473075337bbd9e2. Report an issue: GitHub.