{"record":{"id":"7e76e54379647cf8","repo":"apache/cassandra","slug":"a-maximum-number-of-d-tokens-per-node-is-supporte","errorCode":null,"errorMessage":"A maximum number of %d tokens per node is supported","messagePattern":"A maximum number of (.+?) tokens per node is supported","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":976,"sourceCode":"            throw new ConfigurationException(\"memtable_cleanup_threshold must be <= 0.99, but was \" + conf.memtable_cleanup_threshold, false);\n        if (conf.memtable_cleanup_threshold < 0.1f)\n            logger.warn(\"memtable_cleanup_threshold is set very low [{}], which may cause performance degradation\", conf.memtable_cleanup_threshold);\n\n        if (conf.concurrent_compactors == null)\n            conf.concurrent_compactors = Math.min(8, Math.max(2, Math.min(FBUtilities.getAvailableProcessors(), conf.data_file_directories.length)));\n\n        if (conf.concurrent_compactors <= 0)\n            throw new ConfigurationException(\"concurrent_compactors should be strictly greater than 0, but was \" + conf.concurrent_compactors, false);\n\n        applyConcurrentValidations(conf);\n        applyRepairCommandPoolSize(conf);\n        applyThresholdsValidations(conf);\n\n        if (conf.concurrent_materialized_view_builders <= 0)\n            throw new ConfigurationException(\"concurrent_materialized_view_builders should be strictly greater than 0, but was \" + conf.concurrent_materialized_view_builders, false);\n\n        if (conf.num_tokens != null && conf.num_tokens > MAX_NUM_TOKENS)\n            throw new ConfigurationException(String.format(\"A maximum number of %d tokens per node is supported\", MAX_NUM_TOKENS), false);\n\n        try\n        {\n            // 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)\"\n            preparedStatementsCacheSizeInMiB = (conf.prepared_statements_cache_size == null)\n                                               ? Math.max(10, (int) (Runtime.getRuntime().maxMemory() / 1024 / 1024 / 256))\n                                               : conf.prepared_statements_cache_size.toMebibytes();\n\n            if (preparedStatementsCacheSizeInMiB == 0)\n                throw new NumberFormatException(); // to escape duplicating error message\n\n            // we need this assignment for the Settings virtual table - CASSANDRA-17734\n            conf.prepared_statements_cache_size = new DataStorageSpec.LongMebibytesBound(preparedStatementsCacheSizeInMiB);\n        }\n        catch (NumberFormatException e)\n        {\n            throw new ConfigurationException(\"prepared_statements_cache_size option was set incorrectly to '\"\n                                             + (conf.prepared_statements_cache_size != null ? conf.prepared_statements_cache_size.toString() : null) + \"', supported values are <integer> >= 0.\", false);","sourceCodeStart":958,"sourceCodeEnd":994,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L958-L994","documentation":"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.","triggerScenarios":"Node startup with num_tokens set above MAX_NUM_TOKENS (e.g. num_tokens: 100000).","commonSituations":"Extreme vnode tuning attempts; copying num_tokens from a different distributed system's config; scripts multiplying the token count for load spreading.","solutions":["Lower num_tokens to at most MAX_NUM_TOKENS (check the constant in DatabaseDescriptor for the current limit; typical values are 1-16)","Use the recommended default for your Cassandra version (e.g. 16 in 4.x+, 8 in 3.x)","Remove num_tokens to accept the version default","Restart the node"],"exampleFix":"// before (cassandra.yaml)\nnum_tokens: 100000\n// after\nnum_tokens: 16","handlingStrategy":"validation","validationCode":"int MAX_NUM_TOKENS = 1536; // check DatabaseDescriptor for current limit\nif (conf.numTokens != null && conf.numTokens > MAX_NUM_TOKENS)\n    throw new IllegalArgumentException(\"num_tokens exceeds max \" + MAX_NUM_TOKENS);","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.daemonInitialization(); }\ncatch (ConfigurationException e) { LOG.fatal(e.getMessage()); System.exit(1); }","preventionTips":["Use version-recommended num_tokens (16 or fewer)","Do not inflate tokens for load balancing; adjust allocation strategy instead","Copy token settings only from Cassandra-specific guidance"],"tags":["cassandra","configuration","tokens"],"backgroundTag":"value-out-of-range","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}