{"record":{"id":"a95cf7c66dd19066","repo":"apache/cassandra","slug":"manually-specified-tokens-override-automatic-alloc","errorCode":null,"errorMessage":"manually specified tokens override automatic allocation","messagePattern":"manually specified tokens override automatic allocation","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/dht/BootStrapper.java","lineNumber":227,"sourceCode":"                ProgressEvent currentProgress = new ProgressEvent(ProgressEventType.ERROR, receivedFiles.get(), totalFilesToReceive.get(), throwable.getMessage());\n                fireProgressEvent(\"bootstrap\", currentProgress);\n            }\n        });\n        return bootstrapStreamResult;\n    }\n\n    /**\n     * if initialtoken was specified, use that (split on comma).\n     * otherwise, if allocationKeyspace is specified use the token allocation algorithm to generate suitable tokens\n     * else choose num_tokens tokens at random\n     */\n    public static Collection<Token> getBootstrapTokens(final ClusterMetadata metadata, InetAddressAndPort address) throws ConfigurationException\n    {\n        String allocationKeyspace = DatabaseDescriptor.getAllocateTokensForKeyspace();\n        Integer allocationLocalRf = DatabaseDescriptor.getAllocateTokensForLocalRf();\n        Collection<String> initialTokens = DatabaseDescriptor.getInitialTokens();\n        if (initialTokens.size() > 0 && allocationKeyspace != null)\n            logger.warn(\"manually specified tokens override automatic allocation\");\n\n        // if user specified tokens, use those\n        if (initialTokens.size() > 0)\n        {\n            Collection<Token> tokens = getSpecifiedTokens(metadata, initialTokens);\n            BootstrapDiagnostics.useSpecifiedTokens(address, allocationKeyspace, tokens, DatabaseDescriptor.getNumTokens());\n            return tokens;\n        }\n\n        int numTokens = DatabaseDescriptor.getNumTokens();\n        if (numTokens < 1)\n            throw new ConfigurationException(\"num_tokens must be >= 1\");\n\n        if (allocationKeyspace != null)\n            return allocateTokens(metadata, address, allocationKeyspace, numTokens);\n\n        if (allocationLocalRf != null)\n            return allocateTokens(metadata, address, allocationLocalRf, numTokens);","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/dht/BootStrapper.java#L209-L245","documentation":"BootStrapper.getBootstrapTokens warns that manually configured initial_token values take precedence over automatic token allocation (allocate_tokens_for_local_replication_factor or allocate_tokens_for_keyspace). When both are set, the explicit tokens win and the automatic allocation is skipped, which can silently break the intended even-distribution strategy.","triggerScenarios":"Node bootstrap with both initial_token(s) set in cassandra.yaml and allocate_tokens_for_keyspace or allocate_tokens_for_local_replication_factor configured.","commonSituations":"Operator copies a cassandra.yaml template that sets initial_token while also enabling RF-based allocation; migrating a cluster where old nodes had explicit tokens and new config added allocation settings.","solutions":["Remove initial_token / initial_tokens from cassandra.yaml if you want automatic allocation to be used.","Remove allocate_tokens_for_keyspace / allocate_tokens_for_local_replication_factor if you intend to keep the manually specified tokens.","Verify the resulting token ownership after bootstrap (nodetool ring / nodetool describering) matches your intent."],"exampleFix":"// before (cassandra.yaml)\ninitial_token: -9223372036854775808\nallocate_tokens_for_local_replication_factor: 3\n// after (choose one strategy)\n# initial_token removed so automatic allocation is honored\nallocate_tokens_for_local_replication_factor: 3","handlingStrategy":"validation","validationCode":"# Before bootstrap, verify only ONE token strategy is configured\ngrep -E '^(initial_token|allocate_tokens_for_local_replication_factor|allocate_tokens_for_keyspace):' /etc/cassandra/cassandra.yaml\n# Fail if both initial_token and allocate_tokens_* are set","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pick one token allocation strategy per cluster and standardize cassandra.yaml templates.","Use config management (Ansible/Puppet) to strip initial_token from data-center-wide templates.","Verify token ownership with nodetool ring after bootstrap.","Never copy initial_token values between nodes — each node needs unique tokens."],"tags":["cassandra","bootstrap","token-allocation","configuration"],"backgroundTag":"conflicting-config-options","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"}