apache/cassandra · error · ConfigurationException

Token must be >= 0 and <= 2**127

Error message

Token must be >= 0 and <= 2**127

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/dht/RandomPartitioner.java:252

        @Override
        public Token fromByteBuffer(ByteBuffer bytes, int position, int length)
        {
            return new BigIntegerToken(new BigInteger(ByteBufferUtil.getArray(bytes, position, length)));
        }

        public String toString(Token token)
        {
            BigIntegerToken bigIntegerToken = (BigIntegerToken) token;
            return bigIntegerToken.token.toString();
        }

        public void validate(String token) throws ConfigurationException
        {
            try
            {
                if(!isValidToken(new BigInteger(token)))
                    throw new ConfigurationException("Token must be >= 0 and <= 2**127");
            }
            catch (NumberFormatException e)
            {
                throw new ConfigurationException(e.getMessage());
            }
        }

        public Token fromString(String string)
        {
            return new BigIntegerToken(new BigInteger(string));
        }
    };

    public Token.TokenFactory getTokenFactory()
    {
        return tokenFactory;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. 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
2. If you meant to use Murmur3Partitioner tokens (64-bit signed), switch partitioner to Murmur3Partitioner instead of using RandomPartitioner token values
3. Verify cassandra.yaml `partitioner` matches the format of the tokens you generated
4. Confirm no leading/trailing characters (spaces, 0x prefix) inflate or corrupt the parsed value

Example fix

// before (cassandra.yaml)
initial_token: 340282366920938463463374607431768211455  # == 2**128-1, out of range for RandomPartitioner
// after
initial_token: 170141183460469231731687303715884105728  # <= 2**127-1

BigInteger t = new BigInteger(token);
if (t.signum() < 0 || t.bitLength() > 127)
    throw new IllegalArgumentException("Token out of range for RandomPartitioner: " + token);

boolean isValidToken(BigInteger t) { return t.signum() >= 0 && t.bitLength() <= 127; }

try { partitioner.validateToken(token); } catch (ConfigurationException e) { /* fix token in cassandra.yaml and restart */ }

When it happens

Trigger: 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().

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Invalid Token:
• Token " + token + " contains non-hex digits
• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s
• Invalid value of entire_sstable_stream_throughput_outbound:

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/300f69e94f3ae1c8. Report an issue: GitHub.