apache/cassandra · error · InvalidRequestException

Key length of %d is longer than maximum of %d

Error message

Key length of %d is longer than maximum of %d

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/cql3/Validation.java:54

{

    /**
     * Validates a (full serialized) partition key.
     *
     * @param metadata the metadata for the table of which to check the key.
     * @param key the serialized partition key to check.
     *
     * @throws InvalidRequestException if the provided {@code key} is invalid.
     */
    public static void validateKey(TableMetadata metadata, ByteBuffer key)
    {
        if (key == null || key.remaining() == 0)
            throw new InvalidRequestException("Key may not be empty");

        // check that key can be handled by ByteArrayUtil.writeWithShortLength and ByteBufferUtil.writeWithShortLength
        if (key.remaining() > FBUtilities.MAX_UNSIGNED_SHORT)
        {
            throw new InvalidRequestException("Key length of " + key.remaining() +
                                              " is longer than maximum of " +
                                              FBUtilities.MAX_UNSIGNED_SHORT);
        }

        try
        {
            metadata.partitionKeyType.validate(key);
        }
        catch (MarshalException e)
        {
            throw new InvalidRequestException(e.getMessage());
        }
    }

    public static void checkConstraints(TableMetadata metadata, ByteBuffer key)
    {
        try
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Reduce the key size: hash long values (e.g. MD5/SHA) and use the digest as the partition key.
  2. Move the oversized data into a regular column and use a compact stable identifier as the key.
  3. Add pre-write validation rejecting keys longer than 65535 bytes before sending the statement.
  4. If unavoidable, split the payload across multiple rows keyed by an index.

Example fix

// before
byte[] bigKey = payload.getBytes(); // > 64KB
session.execute("INSERT INTO t (k, v) VALUES (?, ?)", ByteBuffer.wrap(bigKey), val);
// after
byte[] digest = MessageDigest.getInstance("MD5").digest(payload.getBytes());
session.execute("INSERT INTO t (k, v) VALUES (?, ?)", ByteBuffer.wrap(digest), val);
Defensive patterns

Strategy: validation

Validate before calling

final int MAX_KEY = 65535;
if (key.remaining() > MAX_KEY)
    throw new IllegalArgumentException("Key length " + key.remaining() + " exceeds " + MAX_KEY);

Try / catch

try {
    session.execute(stmt);
} catch (InvalidQueryException e) {
    if (e.getMessage().startsWith("Key length of")) {
        throw new IllegalArgumentException("Shrink or hash the partition key", e);
    } else throw e;
}

Prevention

When it happens

Trigger: INSERT/SELECT with a partition key whose serialized ByteBuffer exceeds 65535 remaining bytes, e.g. a very large text or blob key column.

Common situations: Using long UUID strings, JSON payloads, concatenated fields, or file contents as a key column; oversized auto-generated keys from upstream systems.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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