{"record":{"id":"79bd7b5daef9fd2a","repo":"apache/cassandra","slug":"picking-random-token-for-a-single-vnode-you-shou","errorCode":null,"errorMessage":"Picking random token for a single vnode.  You should probably add more vnodes and/or use the automatic token allocation mechanism.","messagePattern":"Picking random token for a single vnode\\.  You should probably add more vnodes and/or use the automatic token allocation mechanism\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/dht/BootStrapper.java","lineNumber":248,"sourceCode":"        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);\n\n        if (numTokens == 1)\n            logger.warn(\"Picking random token for a single vnode.  You should probably add more vnodes and/or use the automatic token allocation mechanism.\");\n\n        Collection<Token> tokens = getRandomTokens(metadata, numTokens);\n        BootstrapDiagnostics.useRandomTokens(address, metadata, numTokens, tokens);\n        return tokens;\n    }\n\n    private static Collection<Token> getSpecifiedTokens(final ClusterMetadata metadata,\n                                                        Collection<String> initialTokens)\n    {\n        logger.info(\"tokens manually specified as {}\",  initialTokens);\n        List<Token> tokens = new ArrayList<>(initialTokens.size());\n        for (String tokenString : initialTokens)\n        {\n            Token token = metadata.tokenMap.partitioner().getTokenFactory().fromString(tokenString);\n            if (metadata.tokenMap.owner(token) != null)\n                throw new ConfigurationException(\"Bootstrapping to existing token \" + tokenString + \" is not allowed (decommission/removenode the old node first).\");\n            tokens.add(token);\n        }","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/dht/BootStrapper.java#L230-L266","documentation":"BootStrapper.getBootstrapTokens falls back to random token generation when no explicit allocation mechanism applies. With numTokens == 1 the random choice yields poor, unpredictable load distribution, so it logs this warning and proceeds. It is a configuration-guidance warning, not a failure.","triggerScenarios":"Bootstrapping a node with num_tokens=1 and neither allocation_keyspace (allocateTokens) nor allocate_tokens_for_local_replication_factor configured, so getRandomTokens is used.","commonSituations":"Legacy single-token-per-node configs carried into new deployments; operators unaware of the automatic token allocation options; test/single-node clusters using default-random tokens.","solutions":["Set num_tokens to a higher value (e.g. 16) in cassandra.yaml before bootstrap.","Configure allocate_tokens_for_keyspace / allocation_keyspace to use the automatic token allocation mechanism.","Set allocate_tokens_for_local_replication_factor for local-RF-aware allocation.","If random tokens are truly intended, ignore the warning; the bootstrap proceeds."],"exampleFix":"# before (cassandra.yaml)\nnum_tokens: 1\n\n# after\nnum_tokens: 16\n# or\nallocate_tokens_for_keyspace: my_keyspace","handlingStrategy":"validation","validationCode":"# fail early on poor token config before bootstrap\ngrep -E '^num_tokens:' conf/cassandra.yaml  # require num_tokens > 1 or allocation settings present","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set num_tokens >= 8-16 for production clusters.","Prefer allocate_tokens_for_keyspace or allocate_tokens_for_local_replication_factor.","Review cassandra.yaml token settings before every bootstrap."],"tags":["bootstrap","tokens","configuration","load-balancing"],"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"}