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

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.

Source

Thrown at src/java/org/apache/cassandra/cql3/restrictions/PartitionKeyRestrictions.java:246

    private ByteBuffer serializeAsPartitionKey(ClusteringElements elements)
    {
        // Single-column partition key: just return the value directly
        if (elements.size() == 1)
            return elements.get(0);

        // Composite partition key: need to build composite
        return CompositeType.build(ByteBufferAccessor.instance, elements.toArray(new ByteBuffer[elements.size()]));
    }

    // repeats the logic of ClusteringPrefix.validate()
    private void validatePartitionKey(ClusteringElements partitionKey)
    {
        int sum = 0;
        for (ByteBuffer columnValue : partitionKey)
        {
            int size = columnValue != null ? columnValue.remaining() : 0;
            if (size > FBUtilities.MAX_UNSIGNED_SHORT)
                throw new InvalidRequestException(String.format("Key length of %d is longer than maximum of %d",
                                                                size,
                                                                FBUtilities.MAX_UNSIGNED_SHORT));
            sum += size;
        }
        if (sum > FBUtilities.MAX_UNSIGNED_SHORT)
            throw new InvalidRequestException(String.format("Key length of %d is longer than maximum of %d",
                                                            sum,
                                                            FBUtilities.MAX_UNSIGNED_SHORT));
    }

    private List<ByteBuffer> toByteBuffers(SortedSet<? extends ClusteringPrefix<?>> clusterings)
    {
        if (clusterings.size() == 1)
        {
            ClusteringPrefix<?> clustering = clusterings.first();
            clustering.validate();
            return Collections.singletonList(clustering.serializeAsPartitionKey());
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Shrink the partition key value to <= 65535 bytes before binding it.
2. Hash or truncate the large value (e.g. MD5/SHA of the payload) and store the raw payload in a regular column instead.
3. Change the schema so the oversized value lives in a non-key column and a compact surrogate key is used.

Example fix

// before
String key = veryLargeJson; // 100 KB
session.execute("INSERT INTO docs (id, body) VALUES (?, ?)", key, body);
// after
String key = DigestUtils.md5Hex(veryLargeJson); // fixed 32-byte key
String body = veryLargeJson;
session.execute("INSERT INTO docs (id, body) VALUES (?, ?)", key, body);

if (key != null && key.remaining() > 65535)
    throw new IllegalArgumentException("partition key component exceeds 65535 bytes: " + key.remaining());

try { session.execute(stmt); }
catch (InvalidRequestException e) {
    if (e.getMessage().startsWith("Key length of")) {
        /* hash/truncate the key and retry */
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

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

• Key may not be empty
• REVOKE operation is not supported by AllowAllAuthorizer
• Key may not be empty
• Key length of %d is longer than maximum of %d
• Column value does not satisfy value constraint for column '<

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