apache/cassandra · error · MarshalException

Invalid version for TimeUUID type: 0x

Error message

Invalid version for TimeUUID type: 0x%s

What it means

TimeUUIDType.validate() also verifies the RFC 4122 version nibble: byte 6's high nibble must be 0x1 (time-based). If not, it throws this MarshalException including the hex version read from the value. This rejects random (v4) or other UUID kinds passed as timeuuid.

Solutions

1. Generate proper time-uuids (TimeUUID.Generator / driver TimeUuid / UUIDs.timeBased()) instead of random UUIDs
2. Use the correct driver codec for timeuuid columns so version is enforced client-side
3. If the value must be a random UUID, change the column type to uuid, not timeuuid
4. Pre-validate in application: (bytes[6] & 0xf0) == 0x10

Example fix

// before
stmt.setUuid(i, UUID.randomUUID()); // v4 -> MarshalException
// after
stmt.setUuid(i, UUIDs.timeBased()); // v1-style time-based UUID

boolean isTimeUuid(byte[] b) { return b != null && b.length == 16 && (b[6] & 0xf0) == 0x10; }

boolean isTimeUuid(java.util.UUID u) { return (u.toString().charAt(14)) == '1'; } // version nibble in canonical string

try { session.execute(insert.bind(value)); } catch (InvalidQueryException e) { if (e.getMessage().contains("Invalid version for TimeUUID")) { /* regenerate as v1 time-based UUID */ } else throw e; }

When it happens

Trigger: Writing a version-4 (random) UUID or v3/v5 UUID into a timeuuid column — the 16-byte length check passes but the version nibble at byte 6 is not 0x10.

Common situations: See trigger scenarios.

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

• UUID should be 16 or 0 bytes
• A CounterId representation is exactly
• A local deletion time should not be a legacy overflowed…
• A local deletion time should not be negative
• A local deletion time should not be negative in

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

Appendix: source

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

    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();
            return buffer;
        }
    }

View on GitHub (pinned to 88fd0f6a0e)