apache/cassandra · error · IllegalArgumentException

Native protocol version

Error message

Native protocol version %d supports only elements with size up to 65535 bytes - but element size is %d bytes

What it means

In native protocol V1/V2, each collection element is length-prefixed with a 16-bit size, so no single element may exceed 65535 bytes. CodecUtils.sizeOfValue (used by elemSize while computing the serialized size of a collection) enforces this and throws IllegalArgumentException when an element's ByteBuffer exceeds that limit.

Solutions

Move to native protocol V3+ where element sizes use 32-bit prefixes
Compress or truncate the large element so each is under 65535 bytes
Store large values in a dedicated column/table (possibly with a pointer in the collection) instead of inside collections

Example fix

// before
cluster.builder().withProtocolVersion(ProtocolVersion.V1); // 64KB element cap
// after
cluster.builder().withProtocolVersion(ProtocolVersion.V4);

Defensive patterns

Strategy: validation

Validate before calling

for (ByteBuffer v : elements) {
    if (v.remaining() > 65535 && protocolVersion.compareTo(ProtocolVersion.V3) < 0) {
        throw new IllegalArgumentException("element exceeds 64KB on V1/V2 protocol");
    }
}

Try / catch

try {
    session.execute(boundStatement);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("65535 bytes")) {
        // compress or relocate the oversized element, then retry
    }
}

Prevention

Use protocol V3+ where element sizes are 32-bit
Enforce a max element size at ingestion for blob/text collection columns
Store large payloads outside collections and reference them by key

When it happens

Trigger: Encoding a collection (list/set/map) containing one element larger than 64KB — e.g. a list<blob> holding a 100KB blob — while executing on protocol V1 or V2.

Common situations: Legacy V1/V2 protocol configs combined with large text/blob collection entries; storing big documents or images inside collection elements; compress-then-insert flows producing oversized elements.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/CodecUtils.java:251

            case V3:
            case V4:
            case V5:
            case V6:
                return 4;
            default:
                throw new IllegalArgumentException(String.valueOf(version));
        }
    }

    private static int sizeOfValue(ByteBuffer value, ProtocolVersion version)
    {
        switch (version)
        {
            case V1:
            case V2:
                int elemSize = value.remaining();
                if (elemSize > 65535)
                    throw new IllegalArgumentException(
                    String.format(
                    "Native protocol version %d supports only elements with size up to 65535 bytes - but element size is %d bytes",
                    version.asInt(), elemSize));
                return 2 + elemSize;
            case V3:
            case V4:
            case V5:
            case V6:
                return value == null ? 4 : 4 + value.remaining();
            default:
                throw new IllegalArgumentException(String.valueOf(version));
        }
    }

    private static int getUnsignedShort(ByteBuffer bb)
    {
        int length = (bb.get() & 0xFF) << 8;
        return length | (bb.get() & 0xFF);

View on GitHub (pinned to 88fd0f6a0e)