apache/cassandra · error · IllegalArgumentException

Length > max length

Error message

Length %d > max length %d

What it means

writeShortLength serializes a length as an unsigned 16-bit short. If the length exceeds FBUtilities.MAX_UNSIGNED_SHORT (65535), the value cannot be represented and IllegalArgumentException is thrown before any bytes are written.

Solutions

1. Use the int-length / vint-length variant for payloads > 65535 bytes
2. Split or chunk data so each piece fits in 65535 bytes
3. Validate payload size before calling and fail early with a clearer message
4. Check which serialization format expects short lengths and switch formats

Example fix

// before
ByteBufferUtil.writeShortLength(bb, blob.remaining()); // fails if > 65535
// after
if (blob.remaining() > FBUtilities.MAX_UNSIGNED_SHORT) {
    ByteBufferUtil.writeWithVIntLength(bb, blob.remaining());
} else {
    ByteBufferUtil.writeShortLength(bb, blob.remaining());
}

// guard before short-length serialization
if (data.remaining() > FBUtilities.MAX_UNSIGNED_SHORT)
    throw new IllegalArgumentException("payload too large for short-length format: " + data.remaining());

try {
    ByteBufferUtil.writeShortLength(bb, len);
} catch (IllegalArgumentException e) {
    // switch to int/vint-length serialization
}

When it happens

Trigger: Calling writeShortLength (directly or via short-length serialization paths) with a byte payload longer than 65535 bytes.

Common situations: Serializing oversized blobs with a short-length format; misusing the short-length helpers for data that requires the int-length (vint/unsigned) variants.

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

• Cannot convert value
• Input date is greater than max supported date
• Invalid 16-bits integer value, expecting 2 bytes but got
• Invalid 32-bits float value, expecting 4 bytes but got
• Invalid 32-bits integer value, expecting 4 bytes but got

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

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/ByteBufferUtil.java:865

    // Doesn't change bb position
    public static int getShortLength(ByteBuffer bb, int position)
    {
        return getUnsignedShort(bb, position);
    }

    // changes bb position
    public static int readShortLength(ByteBuffer bb)
    {
        int length = (bb.get() & 0xFF) << 8;
        return length | (bb.get() & 0xFF);
    }

    // changes bb position
    public static void writeShortLength(ByteBuffer bb, int length)
    {
        if (length > FBUtilities.MAX_UNSIGNED_SHORT)
            throw new IllegalArgumentException(String.format("Length %d > max length %d", length, FBUtilities.MAX_UNSIGNED_SHORT));
        bb.put((byte) ((length >> 8) & 0xFF));
        bb.put((byte) (length & 0xFF));
    }

    // changes bb position
    public static ByteBuffer readBytes(ByteBuffer bb, int length)
    {
        ByteBuffer copy = bb.duplicate();
        copy.limit(copy.position() + length);
        bb.position(bb.position() + length);
        return copy;
    }

    // changes bb position
    public static ByteBuffer readBytesWithShortLength(ByteBuffer bb)
    {
        int length = readShortLength(bb);
        return readBytes(bb, length);

View on GitHub (pinned to 88fd0f6a0e)