apache/cassandra · error · ConfigurationException

A maximum number of %d tokens per node is supported

Error message

A maximum number of %d tokens per node is supported

What it means

Cassandra enforces a hard maximum number of tokens per node (MAX_NUM_TOKENS). If num_tokens in cassandra.yaml exceeds it, applySimpleConfig throws ConfigurationException naming the limit, because allocating that many vnodes is unsupported.

Source

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

            throw new ConfigurationException("memtable_cleanup_threshold must be <= 0.99, but was " + conf.memtable_cleanup_threshold, false);
        if (conf.memtable_cleanup_threshold < 0.1f)
            logger.warn("memtable_cleanup_threshold is set very low [{}], which may cause performance degradation", conf.memtable_cleanup_threshold);

        if (conf.concurrent_compactors == null)
            conf.concurrent_compactors = Math.min(8, Math.max(2, Math.min(FBUtilities.getAvailableProcessors(), conf.data_file_directories.length)));

        if (conf.concurrent_compactors <= 0)
            throw new ConfigurationException("concurrent_compactors should be strictly greater than 0, but was " + conf.concurrent_compactors, false);

        applyConcurrentValidations(conf);
        applyRepairCommandPoolSize(conf);
        applyThresholdsValidations(conf);

        if (conf.concurrent_materialized_view_builders <= 0)
            throw new ConfigurationException("concurrent_materialized_view_builders should be strictly greater than 0, but was " + conf.concurrent_materialized_view_builders, false);

        if (conf.num_tokens != null && conf.num_tokens > MAX_NUM_TOKENS)
            throw new ConfigurationException(String.format("A maximum number of %d tokens per node is supported", MAX_NUM_TOKENS), false);

        try
        {
            // if prepared_statements_cache_size option was set to "auto" then size of the cache should be "max(1/256 of Heap (in MiB), 10MiB)"
            preparedStatementsCacheSizeInMiB = (conf.prepared_statements_cache_size == null)
                                               ? Math.max(10, (int) (Runtime.getRuntime().maxMemory() / 1024 / 1024 / 256))
                                               : conf.prepared_statements_cache_size.toMebibytes();

            if (preparedStatementsCacheSizeInMiB == 0)
                throw new NumberFormatException(); // to escape duplicating error message

            // we need this assignment for the Settings virtual table - CASSANDRA-17734
            conf.prepared_statements_cache_size = new DataStorageSpec.LongMebibytesBound(preparedStatementsCacheSizeInMiB);
        }
        catch (NumberFormatException e)
        {
            throw new ConfigurationException("prepared_statements_cache_size option was set incorrectly to '"
                                             + (conf.prepared_statements_cache_size != null ? conf.prepared_statements_cache_size.toString() : null) + "', supported values are <integer> >= 0.", false);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Lower num_tokens to at most MAX_NUM_TOKENS (check the constant in DatabaseDescriptor for the current limit; typical values are 1-16)
2. Use the recommended default for your Cassandra version (e.g. 16 in 4.x+, 8 in 3.x)
3. Remove num_tokens to accept the version default
4. Restart the node

Example fix

// before (cassandra.yaml)
num_tokens: 100000
// after
num_tokens: 16

int MAX_NUM_TOKENS = 1536; // check DatabaseDescriptor for current limit
if (conf.numTokens != null && conf.numTokens > MAX_NUM_TOKENS)
    throw new IllegalArgumentException("num_tokens exceeds max " + MAX_NUM_TOKENS);

try { DatabaseDescriptor.daemonInitialization(); }
catch (ConfigurationException e) { LOG.fatal(e.getMessage()); System.exit(1); }

When it happens

Trigger: Node startup with num_tokens set above MAX_NUM_TOKENS (e.g. num_tokens: 100000).

Common situations: Extreme vnode tuning attempts; copying num_tokens from a different distributed system's config; scripts multiplying the token count for load spreading.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• initial_token was set but num_tokens is not!
• 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/7e76e54379647cf8. Report an issue: GitHub.