apache/cassandra · error · MarshalException

UUID should be 16 or 0 bytes

Error message

UUID should be 16 or 0 bytes (%d)

What it means

TimeUUIDType's validate() enforces that a TimeUUID value is either empty (null marker) or exactly 16 bytes. Any other length throws this MarshalException with the offending size. It protects downstream code that reads fixed byte offsets for timestamp/version fields.

Solutions

  1. Ensure the client sends a full 16-byte UUID (use driver UUID codecs instead of raw bytes)
  2. For NULL, send an empty (0-length) value rather than a short byte array
  3. Check ETL/serialization code for truncation (e.g. slicing 8 bytes instead of 16)
  4. Validate values in the application before writes: length check + version nibble

Example fix

// before
byte[] v = Arrays.copyOf(uuidBytes, 8); // truncated
// after
if (uuidBytes.length != 16) throw new IllegalArgumentException("timeuuid must be 16 bytes");
byte[] v = uuidBytes;
Defensive patterns

Strategy: validation

Validate before calling

if (value != null && value.length != 16) throw new IllegalArgumentException("timeuuid must be exactly 16 bytes, got " + value.length);

Try / catch

try { session.execute(insert.bind(value)); } catch (InvalidQueryException e) { if (e.getMessage().startsWith("UUID should be 16 or 0 bytes")) { /* fix payload length and retry */ } else throw e; }

Prevention

When it happens

Trigger: Inserting/updating a timeuuid column with a value whose serialized size is not 0 or 16 bytes — e.g. truncated binary input, a malformed driver payload, or writing raw bytes of wrong length through CQL binary protocol.

Common situations: Application bugs slicing UUID buffers, hand-built binary protocol frames, ETL jobs writing string/hex values of the wrong length, or timeuuid columns receiving arbitrary byte arrays.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/TimeUUID.java:342

    }

    @Override
    public int compareTo(TimeUUID that)
    {
        return this.uuidTimestamp != that.uuidTimestamp
               ? Long.compare(this.uuidTimestamp, that.uuidTimestamp)
               : Long.compare(this.lsb, that.lsb);
    }

    protected static abstract class AbstractSerializer<T extends TimeUUID> extends TypeSerializer<T>
    {
        public <V> void validate(V value, ValueAccessor<V> accessor) throws MarshalException
        {
            if (accessor.isEmpty(value))
                return;

            if (accessor.size(value) != 16)
                throw new MarshalException(String.format("UUID should be 16 or 0 bytes (%d)", accessor.size(value)));

            if ((accessor.getByte(value, 6) & 0xf0) != 0x10)
                throw new MarshalException(String.format("Invalid version for TimeUUID type: 0x%s", Integer.toHexString((accessor.getByte(value, 0) >> 4) & 0xf)));
        }

        public String toString(T value)
        {
            return value == null ? "" : value.toString();
        }

        public ByteBuffer serialize(T value)
        {
            if (value == null)
                return EMPTY_BYTE_BUFFER;
            ByteBuffer buffer = ByteBuffer.allocate(16);
            buffer.putLong(value.msb());
            buffer.putLong(value.lsb());
            buffer.flip();

View on GitHub (pinned to 88fd0f6a0e)