{"record":{"id":"4078ea050e81ea05","repo":"apache/cassandra","slug":"key-length-of-d-is-longer-than-maximum-of-d-4078ea","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/Validation.java","lineNumber":54,"sourceCode":"{\n\n    /**\n     * Validates a (full serialized) partition key.\n     *\n     * @param metadata the metadata for the table of which to check the key.\n     * @param key the serialized partition key to check.\n     *\n     * @throws InvalidRequestException if the provided {@code key} is invalid.\n     */\n    public static void validateKey(TableMetadata metadata, ByteBuffer key)\n    {\n        if (key == null || key.remaining() == 0)\n            throw new InvalidRequestException(\"Key may not be empty\");\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 \" +\n                                              FBUtilities.MAX_UNSIGNED_SHORT);\n        }\n\n        try\n        {\n            metadata.partitionKeyType.validate(key);\n        }\n        catch (MarshalException e)\n        {\n            throw new InvalidRequestException(e.getMessage());\n        }\n    }\n\n    public static void checkConstraints(TableMetadata metadata, ByteBuffer key)\n    {\n        try\n        {","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/Validation.java#L36-L72","documentation":"validateKey also enforces that a partition key fits in an unsigned short length prefix (65535 bytes), because Cassandra serializes keys with ByteArrayUtil.writeWithShortLength/ByteBufferUtil.writeWithShortLength. Keys longer than FBUtilities.MAX_UNSIGNED_SHORT are rejected with InvalidRequestException naming both the actual and maximum length.","triggerScenarios":"INSERT/SELECT with a partition key whose serialized ByteBuffer exceeds 65535 remaining bytes, e.g. a very large text or blob key column.","commonSituations":"Using long UUID strings, JSON payloads, concatenated fields, or file contents as a key column; oversized auto-generated keys from upstream systems.","solutions":["Reduce the key size: hash long values (e.g. MD5/SHA) and use the digest as the partition key.","Move the oversized data into a regular column and use a compact stable identifier as the key.","Add pre-write validation rejecting keys longer than 65535 bytes before sending the statement.","If unavoidable, split the payload across multiple rows keyed by an index."],"exampleFix":"// before\nbyte[] bigKey = payload.getBytes(); // > 64KB\nsession.execute(\"INSERT INTO t (k, v) VALUES (?, ?)\", ByteBuffer.wrap(bigKey), val);\n// after\nbyte[] digest = MessageDigest.getInstance(\"MD5\").digest(payload.getBytes());\nsession.execute(\"INSERT INTO t (k, v) VALUES (?, ?)\", ByteBuffer.wrap(digest), val);","handlingStrategy":"validation","validationCode":"final int MAX_KEY = 65535;\nif (key.remaining() > MAX_KEY)\n    throw new IllegalArgumentException(\"Key length \" + key.remaining() + \" exceeds \" + MAX_KEY);","typeGuard":null,"tryCatchPattern":"try {\n    session.execute(stmt);\n} catch (InvalidQueryException e) {\n    if (e.getMessage().startsWith(\"Key length of\")) {\n        throw new IllegalArgumentException(\"Shrink or hash the partition key\", e);\n    } else throw e;\n}","preventionTips":["Hash long natural keys instead of storing them raw","Keep key columns compact (UUID/int/text with bounded length)","Assert key size in data-ingestion pipelines"],"tags":["cassandra","cql","validation","key-size"],"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"}