apache/cassandra · error · ConfigurationException

The number of initial tokens (by initial_token) specified (%

Error message

The number of initial tokens (by initial_token) specified (%s) is different from num_tokens value (%s)

What it means

During startup, DatabaseDescriptor validates the cassandra.yaml configuration. If initial_token was set, the number of comma-separated tokens it defines must exactly match the configured num_tokens count; otherwise Cassandra cannot construct a consistent token ring, so it aborts startup with a ConfigurationException.

Source

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

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

    // definitely not safe for tools + clients - implicitly instantiates StorageService
    public static void applySnitch()
    {
        boolean hasLegacyConfig = conf.endpoint_snitch != null;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Make the number of comma-separated tokens in initial_token exactly equal num_tokens in cassandra.yaml
  2. If you do not need specific tokens, remove initial_token entirely and let num_tokens/allocate_tokens_for_local_replication_factor assign tokens automatically
  3. If you intend a single-token node, set num_tokens: 1 and provide exactly one token

Example fix

# before (cassandra.yaml)
num_tokens: 16
initial_token: 0, 34028236692093846346337460743176821145
# after
num_tokens: 2
initial_token: 0, 34028236692093846346337460743176821145
# or simply remove initial_token and keep num_tokens: 16
Defensive patterns

Strategy: validation

Validate before calling

if (tokens.size() != numTokens) throw new IllegalStateException("token count mismatch");

Try / catch

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* align token counts */ }

Prevention

When it happens

Trigger: cassandra.yaml sets initial_token with N comma-separated tokens while num_tokens (or an externally supplied token count) is M != N; the check tokens.size() != conf.num_tokens throws before the node joins the ring.

Common situations: Operators copy an initial_token from another node (single token) but leave num_tokens at its default (16 in modern versions, 1 in older ones); upgrading a vnode cluster and hand-specifying tokens without adjusting num_tokens.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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