apache/cassandra · error · InvalidRequestException

The specified 'key' is not within the provided token value b

Error message

The specified 'key' is not within the provided token value bounds.

What it means

After parsing the requested 'key', getBounds() verifies the decorated key falls within the token range constraints of the query. If the key's token is outside the startToken/endToken bounds (i.e. the key equality conflicts with the token filters), InvalidRequestException(KEY_NOT_WITHIN_BOUNDS_ERROR) is thrown.

Source

Thrown at src/java/org/apache/cassandra/db/virtual/PartitionKeyStatsTable.java:330

            if (expression.column().name.toString().equals(COLUMN_KEY))
            {
                if (expression.operator() != Operator.EQ)
                    throw new InvalidRequestException(KEY_ONLY_EQUALS_ERROR);

                String keyString = UTF8Type.instance.compose(expression.getIndexValue());
                ByteBuffer keyAsBB;
                try
                {
                    keyAsBB = target.partitionKeyType.fromString(keyString);
                }
                catch (MarshalException ex)
                {
                    throw new InvalidRequestException(ex.getMessage());
                }
                DecoratedKey decoratedKey = target.partitioner.decorateKey(keyAsBB);

                if (!DataRange.forKeyRange(new Range<>(startToken.minKeyBound(), endToken.maxKeyBound())).contains(decoratedKey.getToken().minKeyBound()))
                    throw new InvalidRequestException(KEY_NOT_WITHIN_BOUNDS_ERROR);

                return Bounds.bounds(decoratedKey, true, decoratedKey, true);
            }
        }
        return Bounds.bounds(startToken.minKeyBound(), true, endToken.maxKeyBound(), true);
    }

    private static Cell<?> cell(ColumnMetadata column, ByteBuffer value)
    {
        return BufferCell.live(column, 1L, value);
    }

    @Override
    public TableMetadata metadata()
    {
        return this.metadata;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Remove the token constraints or pick a 'key' whose token lies within them.
Recompute the token of the key (`SELECT token(pk) FROM ...`) and set bounds around it.
Drop the key filter and query by token range alone if many partitions are desired.

Example fix

// before
SELECT * FROM system_views.partitions WHERE token(pk) > -100 AND token(pk) < 0 AND key = 'pk_out_of_range';
// after
SELECT * FROM system_views.partitions WHERE token(pk) > -100 AND token(pk) < 100 AND key = 'pk_in_range';

Defensive patterns

Strategy: validation

Validate before calling

// Compute the key's token and check it against the token bounds before querying
long token = Murmur3TokenFactory /* or via SELECT token(pk) */;
// only issue query if startToken < token < endToken
if (!(token > startToken && token < endToken))
    throw new IllegalArgumentException("key not within token bounds");

Try / catch

try { rs = session.execute(query); }
catch (com.datastax.oss.driver.api.core.servererrors.InvalidQueryException e) {
    if (e.getMessage().contains("not within the provided token value bounds")) { /* adjust bounds or key, retry */ }
    else throw e;
}

Prevention

Derive token bounds from the key itself (`SELECT token(pk) ...`) instead of hand-computing.
Confirm partitioner is Murmur3Partitioner when reusing token values.
Avoid mixing fixed key filters with token windows from other queries.

When it happens

Trigger: Combining `WHERE key = 'k'` with token-range predicates (token(pk) > X AND token(pk) < Y) where k's token is not inside (X, Y); conflicting/mistyped token bounds.

Common situations: Hand-computed token bounds that exclude the key; copy-pasted token values from a different partitioner; scripts that build token windows but reference a fixed key.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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