{"record":{"id":"300f69e94f3ae1c8","repo":"apache/cassandra","slug":"token-must-be-0-and-2-127","errorCode":null,"errorMessage":"Token must be >= 0 and <= 2**127","messagePattern":"Token must be >= 0 and <= 2\\*\\*127","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/dht/RandomPartitioner.java","lineNumber":252,"sourceCode":"\n        @Override\n        public Token fromByteBuffer(ByteBuffer bytes, int position, int length)\n        {\n            return new BigIntegerToken(new BigInteger(ByteBufferUtil.getArray(bytes, position, length)));\n        }\n\n        public String toString(Token token)\n        {\n            BigIntegerToken bigIntegerToken = (BigIntegerToken) token;\n            return bigIntegerToken.token.toString();\n        }\n\n        public void validate(String token) throws ConfigurationException\n        {\n            try\n            {\n                if(!isValidToken(new BigInteger(token)))\n                    throw new ConfigurationException(\"Token must be >= 0 and <= 2**127\");\n            }\n            catch (NumberFormatException e)\n            {\n                throw new ConfigurationException(e.getMessage());\n            }\n        }\n\n        public Token fromString(String string)\n        {\n            return new BigIntegerToken(new BigInteger(string));\n        }\n    };\n\n    public Token.TokenFactory getTokenFactory()\n    {\n        return tokenFactory;\n    }\n","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/dht/RandomPartitioner.java#L234-L270","documentation":"RandomPartitioner.TokenTokenMetadataValidator.validate() parses a user-supplied token string as a BigInteger and requires it to be in the partitioner's valid range [0, 2**127). If the parsed value is negative or >= 2**127 (or the string is not a number, caught separately), it throws ConfigurationException with this message. This validation runs when tokens are supplied via cassandra.yaml (initial_token) or nodetool.","triggerScenarios":"Supplying an initial_token in cassandra.yaml that is negative or >= 2**127; calling RandomPartitioner.TokenValidator.validate(token) directly with an out-of-range BigInteger string; node startup / token configuration validation paths that call validate().","commonSituations":"Copy-pasting a 160-bit token generated for a different partitioner into an older 127-bit RandomPartitioner config; hand-generating tokens with a random 128+ bit generator; including a minus sign; whitespace or hex notation that BigInteger parses but exceeds the range.","solutions":["Regenerate the token in [0, 2**127): e.g. use `python3 -c \"import random; print(random.randint(0, 2**127-1))\"` or the recommended random-token generation for RandomPartitioner","If you meant to use Murmur3Partitioner tokens (64-bit signed), switch partitioner to Murmur3Partitioner instead of using RandomPartitioner token values","Verify cassandra.yaml `partitioner` matches the format of the tokens you generated","Confirm no leading/trailing characters (spaces, 0x prefix) inflate or corrupt the parsed value"],"exampleFix":"// before (cassandra.yaml)\ninitial_token: 340282366920938463463374607431768211455  # == 2**128-1, out of range for RandomPartitioner\n// after\ninitial_token: 170141183460469231731687303715884105728  # <= 2**127-1","handlingStrategy":"validation","validationCode":"BigInteger t = new BigInteger(token);\nif (t.signum() < 0 || t.bitLength() > 127)\n    throw new IllegalArgumentException(\"Token out of range for RandomPartitioner: \" + token);","typeGuard":"boolean isValidToken(BigInteger t) { return t.signum() >= 0 && t.bitLength() <= 127; }","tryCatchPattern":"try { partitioner.validateToken(token); } catch (ConfigurationException e) { /* fix token in cassandra.yaml and restart */ }","preventionTips":["Generate tokens with a generator bound to the partitioner's range, not arbitrary random bytes","Always confirm `partitioner` in cassandra.yaml matches token format","Use Cassandra's provided token-generation tooling instead of hand-computed values"],"tags":["configuration","token","partitioner","validation"],"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"}