{"record":{"id":"1f5a843dd535130f","repo":"apache/cassandra","slug":"key-length-of-d-is-longer-than-maximum-of-d-1f5a84","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/restrictions/PartitionKeyRestrictions.java","lineNumber":246,"sourceCode":"    private ByteBuffer serializeAsPartitionKey(ClusteringElements elements)\n    {\n        // Single-column partition key: just return the value directly\n        if (elements.size() == 1)\n            return elements.get(0);\n\n        // Composite partition key: need to build composite\n        return CompositeType.build(ByteBufferAccessor.instance, elements.toArray(new ByteBuffer[elements.size()]));\n    }\n\n    // repeats the logic of ClusteringPrefix.validate()\n    private void validatePartitionKey(ClusteringElements partitionKey)\n    {\n        int sum = 0;\n        for (ByteBuffer columnValue : partitionKey)\n        {\n            int size = columnValue != null ? columnValue.remaining() : 0;\n            if (size > FBUtilities.MAX_UNSIGNED_SHORT)\n                throw new InvalidRequestException(String.format(\"Key length of %d is longer than maximum of %d\",\n                                                                size,\n                                                                FBUtilities.MAX_UNSIGNED_SHORT));\n            sum += size;\n        }\n        if (sum > FBUtilities.MAX_UNSIGNED_SHORT)\n            throw new InvalidRequestException(String.format(\"Key length of %d is longer than maximum of %d\",\n                                                            sum,\n                                                            FBUtilities.MAX_UNSIGNED_SHORT));\n    }\n\n    private List<ByteBuffer> toByteBuffers(SortedSet<? extends ClusteringPrefix<?>> clusterings)\n    {\n        if (clusterings.size() == 1)\n        {\n            ClusteringPrefix<?> clustering = clusterings.first();\n            clustering.validate();\n            return Collections.singletonList(clustering.serializeAsPartitionKey());\n        }","sourceCodeStart":228,"sourceCodeEnd":264,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/restrictions/PartitionKeyRestrictions.java#L228-L264","documentation":"Cassandra stores partition key components on disk with a 16-bit length prefix, so no single key component may exceed 65535 bytes (FBUtilities.MAX_UNSIGNED_SHORT). When a bound value for a partition key column exceeds that limit, the query is rejected as an InvalidRequestException before execution.","triggerScenarios":"Executing an INSERT/SELECT whose partition key value (single component, this branch) has more than 65535 remaining bytes, e.g. a huge text/blob primary key column value supplied via a bound statement or literal.","commonSituations":"Using unbounded text/varchar or blob columns as partition keys and inserting large payloads (serialized documents, base64 data); users treating the partition key as a data bucket instead of a lookup key.","solutions":["Shrink the partition key value to <= 65535 bytes before binding it.","Hash or truncate the large value (e.g. MD5/SHA of the payload) and store the raw payload in a regular column instead.","Change the schema so the oversized value lives in a non-key column and a compact surrogate key is used."],"exampleFix":"// before\nString key = veryLargeJson; // 100 KB\nsession.execute(\"INSERT INTO docs (id, body) VALUES (?, ?)\", key, body);\n// after\nString key = DigestUtils.md5Hex(veryLargeJson); // fixed 32-byte key\nString body = veryLargeJson;\nsession.execute(\"INSERT INTO docs (id, body) VALUES (?, ?)\", key, body);","handlingStrategy":"validation","validationCode":"if (key != null && key.remaining() > 65535)\n    throw new IllegalArgumentException(\"partition key component exceeds 65535 bytes: \" + key.remaining());","typeGuard":null,"tryCatchPattern":"try { session.execute(stmt); }\ncatch (InvalidRequestException e) {\n    if (e.getMessage().startsWith(\"Key length of\")) {\n        /* hash/truncate the key and retry */\n    } else throw e;\n}","preventionTips":["Schema-design time: avoid unbounded text/blob columns in partition keys.","Validate key byte length in the application before bind.","Prefer fixed-size surrogate keys (UUID/hash)."],"tags":["cassandra","cql","partition-key","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"}