{"record":{"id":"52bf7309e2f37a30","repo":"apache/cassandra","slug":"the-number-of-initial-tokens-by-initial-token-sp","errorCode":null,"errorMessage":"The number of initial tokens (by initial_token) specified (%s) is different from num_tokens value (%s)","messagePattern":"The number of initial tokens \\(by initial_token\\) specified \\((.+?)\\) is different from num_tokens value \\((.+?)\\)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":1755,"sourceCode":"        applyTokensConfig(conf);\n    }\n\n    static void applyTokensConfig(Config conf)\n    {\n        if (conf.initial_token != null)\n        {\n            Collection<String> tokens = tokensFromString(conf.initial_token);\n            if (conf.num_tokens == null)\n            {\n                if (tokens.size() == 1)\n                    conf.num_tokens = 1;\n                else\n                    throw new ConfigurationException(\"initial_token was set but num_tokens is not!\", false);\n            }\n\n            if (tokens.size() != conf.num_tokens)\n            {\n                throw new ConfigurationException(String.format(\"The number of initial tokens (by initial_token) specified (%s) is different from num_tokens value (%s)\",\n                                                               tokens.size(),\n                                                               conf.num_tokens),\n                                                 false);\n            }\n\n            for (String token : tokens)\n                partitioner.getTokenFactory().validate(token);\n        }\n        else if (conf.num_tokens == null)\n        {\n            conf.num_tokens = 1;\n        }\n    }\n\n    // definitely not safe for tools + clients - implicitly instantiates StorageService\n    public static void applySnitch()\n    {\n        boolean hasLegacyConfig = conf.endpoint_snitch != null;","sourceCodeStart":1737,"sourceCodeEnd":1773,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L1737-L1773","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make the number of comma-separated tokens in initial_token exactly equal num_tokens in cassandra.yaml","If you do not need specific tokens, remove initial_token entirely and let num_tokens/allocate_tokens_for_local_replication_factor assign tokens automatically","If you intend a single-token node, set num_tokens: 1 and provide exactly one token"],"exampleFix":"# before (cassandra.yaml)\nnum_tokens: 16\ninitial_token: 0, 34028236692093846346337460743176821145\n# after\nnum_tokens: 2\ninitial_token: 0, 34028236692093846346337460743176821145\n# or simply remove initial_token and keep num_tokens: 16","handlingStrategy":"validation","validationCode":"if (tokens.size() != numTokens) throw new IllegalStateException(\"token count mismatch\");","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { /* align token counts */ }","preventionTips":["Keep initial_token count equal to num_tokens"],"tags":["configuration","startup","vnodes","tokens"],"backgroundTag":"invalid-config-value","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"}