apache/cassandra · error · org.apache.cassandra.exceptions.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

ClusteringPrefix.validate() enforces that each clustering component, and the total serialized clustering size, fit within FBUtilities.MAX_UNSIGNED_SHORT (65535 bytes), because component lengths are encoded as unsigned shorts. Exceeding this raises InvalidRequestException.

Source

Thrown at src/java/org/apache/cassandra/db/ClusteringPrefix.java:340

    default byte[] arrayAt(int i)
    {
        return accessor().toArray(get(i));
    }

    default String stringAt(int i, ClusteringComparator comparator)
    {
        return comparator.subtype(i).getString(get(i), accessor());
    }

    default void validate()
    {
        ValueAccessor<V> accessor = accessor();
        int sum = 0;
        for (V v : getRawValues())
        {
            if (v != null && accessor.size(v) > FBUtilities.MAX_UNSIGNED_SHORT)
                throw new InvalidRequestException(String.format("Key length of %d is longer than maximum of %d",
                                                                dataSize(),
                                                                FBUtilities.MAX_UNSIGNED_SHORT));
            sum += v == null ? 0 : accessor.size(v);
        }
        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));
    }

    default void validate(int i, ClusteringComparator comparator)
    {
        comparator.subtype(i).validate(get(i), accessor());
    }

    /**
     * Adds the data of this clustering prefix to the provided Digest instance.
     *

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Reduce the size of clustering key values (hash, truncate, or move large payloads to a regular column).
2. Validate key lengths in the application before writing.
3. Redesign the schema so large values are stored in value columns, not clustering columns.

Example fix

// before
INSERT INTO t (pk, very_long_clustering_key, v) VALUES (1, <200000-byte string>, 'x');
// after
INSERT INTO t (pk, ck_hash, payload) VALUES (1, md5(payload), <large string stored as value>);

int total = 0;
for (byte[] v : clusteringValues) {
    if (v.length > 65535) throw new IllegalArgumentException("Clustering component too long");
    total += v.length;
}
if (total > 65535) throw new IllegalArgumentException("Clustering key too long");

try { session.execute(insert); } catch (InvalidRequestException e) { if (e.getMessage().contains("longer than maximum")) shrinkKey(); else throw e; }

When it happens

Trigger: Writing a row whose clustering key component (e.g. a text partition of a time-series key) exceeds 65535 bytes, or whose combined clustering components exceed the limit.

Common situations: Using very long strings/blobs as clustering keys; application-generated composite keys that concatenate large values; importing data from systems without key-length limits.

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 length of %d is longer than maximum of %d
• REVOKE operation is not supported by AllowAllAuthorizer
• %s is not a valid data resource name
• %s is not a valid function resource name
• Maximum number of workers must not be negative

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