{"record":{"id":"e8466c733da523ff","repo":"apache/cassandra","slug":"the-specified-key-is-not-within-the-provided-tok","errorCode":null,"errorMessage":"The specified 'key' is not within the provided token value bounds.","messagePattern":"The specified 'key' is not within the provided token value bounds\\.","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/virtual/PartitionKeyStatsTable.java","lineNumber":330,"sourceCode":"            if (expression.column().name.toString().equals(COLUMN_KEY))\n            {\n                if (expression.operator() != Operator.EQ)\n                    throw new InvalidRequestException(KEY_ONLY_EQUALS_ERROR);\n\n                String keyString = UTF8Type.instance.compose(expression.getIndexValue());\n                ByteBuffer keyAsBB;\n                try\n                {\n                    keyAsBB = target.partitionKeyType.fromString(keyString);\n                }\n                catch (MarshalException ex)\n                {\n                    throw new InvalidRequestException(ex.getMessage());\n                }\n                DecoratedKey decoratedKey = target.partitioner.decorateKey(keyAsBB);\n\n                if (!DataRange.forKeyRange(new Range<>(startToken.minKeyBound(), endToken.maxKeyBound())).contains(decoratedKey.getToken().minKeyBound()))\n                    throw new InvalidRequestException(KEY_NOT_WITHIN_BOUNDS_ERROR);\n\n                return Bounds.bounds(decoratedKey, true, decoratedKey, true);\n            }\n        }\n        return Bounds.bounds(startToken.minKeyBound(), true, endToken.maxKeyBound(), true);\n    }\n\n    private static Cell<?> cell(ColumnMetadata column, ByteBuffer value)\n    {\n        return BufferCell.live(column, 1L, value);\n    }\n\n    @Override\n    public TableMetadata metadata()\n    {\n        return this.metadata;\n    }\n","sourceCodeStart":312,"sourceCodeEnd":348,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/virtual/PartitionKeyStatsTable.java#L312-L348","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nSELECT * FROM system_views.partitions WHERE token(pk) > -100 AND token(pk) < 0 AND key = 'pk_out_of_range';\n// after\nSELECT * FROM system_views.partitions WHERE token(pk) > -100 AND token(pk) < 100 AND key = 'pk_in_range';","handlingStrategy":"validation","validationCode":"// Compute the key's token and check it against the token bounds before querying\nlong token = Murmur3TokenFactory /* or via SELECT token(pk) */;\n// only issue query if startToken < token < endToken\nif (!(token > startToken && token < endToken))\n    throw new IllegalArgumentException(\"key not within token bounds\");","typeGuard":null,"tryCatchPattern":"try { rs = session.execute(query); }\ncatch (com.datastax.oss.driver.api.core.servererrors.InvalidQueryException e) {\n    if (e.getMessage().contains(\"not within the provided token value bounds\")) { /* adjust bounds or key, retry */ }\n    else throw e;\n}","preventionTips":["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."],"tags":["cassandra","virtual-table","token","bounds"],"backgroundTag":"invalid-argument-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"}