apache/cassandra · error · IllegalArgumentException

A CounterId representation is exactly

Error message

A CounterId representation is exactly ${LENGTH} bytes

What it means

A CounterId wraps exactly LENGTH (16) bytes in a ByteBuffer. The private constructor validates the buffer's remaining bytes and throws IllegalArgumentException if the representation has any other size.

Solutions

1. Ensure the ByteBuffer is backed by exactly 16 bytes (e.g. ByteBuffer.wrap(idBytes) with idBytes.length == 16)
2. Use CounterId.wrap(ByteBuffer) / CounterId.fromString / generate() instead of constructing raw buffers
3. Validate input length before calling: if (buf.remaining() != 16) handle the error

Example fix

// before
CounterId id = CounterId.wrap(ByteBuffer.wrap(new byte[8]));
// after
byte[] raw = new byte[16];
CounterId id = CounterId.wrap(ByteBuffer.wrap(raw));

CounterId safeWrap(ByteBuffer buf) {
    if (buf == null || buf.remaining() != 16)
        throw new IllegalArgumentException("CounterId needs 16 bytes, got " + (buf == null ? 0 : buf.remaining()));
    return CounterId.wrap(buf);
}

try {
    CounterId id = CounterId.wrap(buf);
} catch (IllegalArgumentException e) {
    // wrong-length representation: corrupt data or wrong format
}

When it happens

Trigger: CounterId.wrap / private construction with a ByteBuffer whose remaining() != 16, e.g. a truncated or padded counter-id column name, or a wrong-length byte array converted to a buffer.

Common situations: Corrupted counter columns, parsing metadata of the wrong format, hand-crafting counter IDs from UUIDs/strings without confirming byte length.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Illegal capacity
• Invalid version value
• Only single character delimiters supported, was
• Reader index should be non-negative, but was
• Size must be non-negative

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

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/CounterId.java:82

     * For performance reasons, this function interns the provided ByteBuffer.
     */
    public static CounterId wrap(ByteBuffer id)
    {
        return new CounterId(id);
    }

    public static CounterId wrap(ByteBuffer bb, int offset)
    {
        ByteBuffer dup = bb.duplicate();
        dup.position(offset);
        dup.limit(dup.position() + LENGTH);
        return wrap(dup);
    }

    private CounterId(ByteBuffer id)
    {
        if (id.remaining() != LENGTH)
            throw new IllegalArgumentException("A CounterId representation is exactly " + LENGTH + " bytes");

        this.id = id;
    }

    public static CounterId generate()
    {
        return new CounterId(ByteBuffer.wrap(nextTimeUUIDAsBytes()));
    }

    /*
     * For performance reasons, this function returns a reference to the internal ByteBuffer. Clients not modify the
     * result of this function.
     */
    public ByteBuffer bytes()
    {
        return id;
    }

View on GitHub (pinned to 88fd0f6a0e)