{"record":{"id":"7c9011bb0644f4f0","repo":"apache/cassandra","slug":"key-length-of-d-is-longer-than-maximum-of-d","errorCode":null,"errorMessage":"Key length of %d is longer than maximum of %d","messagePattern":"Key length of (.+?) is longer than maximum of (.+?)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/QueryProcessor.java","lineNumber":297,"sourceCode":"\n    public Prepared getPrepared(MD5Digest id)\n    {\n        return preparedStatements.getIfPresent(id);\n    }\n\n    public static void validateKey(ByteBuffer key) throws InvalidRequestException\n    {\n        if (key == null || key.remaining() == 0)\n        {\n            throw new InvalidRequestException(\"Key may not be empty\");\n        }\n        if (key == ByteBufferUtil.UNSET_BYTE_BUFFER)\n            throw new InvalidRequestException(\"Key may not be unset\");\n\n        // check that key can be handled by ByteArrayUtil.writeWithShortLength and ByteBufferUtil.writeWithShortLength\n        if (key.remaining() > FBUtilities.MAX_UNSIGNED_SHORT)\n        {\n            throw new InvalidRequestException(\"Key length of \" + key.remaining() +\n                                              \" is longer than maximum of \" + FBUtilities.MAX_UNSIGNED_SHORT);\n        }\n    }\n\n    public ResultMessage processStatement(CQLStatement statement, QueryState queryState, QueryOptions options, Dispatcher.RequestTime requestTime)\n    throws RequestExecutionException, RequestValidationException\n    {\n        logger.trace(\"Process {} @CL.{}\", statement, options.getConsistency());\n        ClientState clientState = queryState.getClientState();\n        statement.authorize(clientState);\n        statement.validate(clientState);\n\n        ResultMessage result = options.getConsistency() == ConsistencyLevel.NODE_LOCAL\n                             ? processNodeLocalStatement(statement, queryState, options)\n                             : statement.execute(queryState, options, requestTime);\n\n        return result == null ? new ResultMessage.Void() : result;\n    }","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/QueryProcessor.java#L279-L315","documentation":"validateKey() enforces that a partition key fits in an unsigned short length prefix (65535 bytes), because keys are written with ByteBufferUtil/ByteArrayUtil writeWithShortLength on the wire and in SSTables. Longer keys would corrupt the length-prefixed encoding.","triggerScenarios":"Binding a partition key whose serialized byte length exceeds FBUtilities.MAX_UNSIGNED_SHORT (65535 bytes), e.g. very large text/blob keys.","commonSituations":"Using huge composite keys or blob keys built from concatenated data; schema design without key-size limits; migrating from stores without such limits.","solutions":["Reduce the key size (truncate, hash, or use a surrogate key) so it stays under 65535 bytes.","Redesign the schema to use a smaller key with the large data moved to regular columns.","Add application-side length validation on keys before binding."],"exampleFix":"// before\nstmt.bind(hugeBlob); // > 65535 bytes\n// after\nbyte[] key = DigestUtils.sha256(hugeBlob); // fixed 32-byte surrogate key\nstmt.bind(key);","handlingStrategy":"validation","validationCode":"if (key.remaining() > 65535) throw new IllegalArgumentException(\"partition key exceeds 65535 bytes: \" + key.remaining());","typeGuard":null,"tryCatchPattern":"try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().startsWith(\"Key length of\")) { /* hash or shrink key */ } }","preventionTips":["Cap key size in application data models","Use hashed surrogate keys for large natural keys","Check composite key component sizes"],"tags":["cql","partition-key","size-limit"],"backgroundTag":"payload-too-large","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"}