apache/cassandra · error · MarshalException

TimeUUID supports only version 1 UUIDs

Error message

TimeUUID supports only version 1 UUIDs

What it means

Fired in AbstractTimeUUIDType.fromString when parsing a CQL literal: the UUID is valid but its version nibble is not 1, so it is a random (v4) or other UUID, not a timeuuid. The string is rejected because only version-1 (time-based) UUIDs can be stored in a timeuuid column.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/AbstractTimeUUIDType.java:163

    protected static long reorderBackTimestampBytes(long input)
    {
        // In a time-based UUID the high bits are significantly more shuffled than in other UUIDs - if [X] represents a
        // 16-bit tuple, [1][2][3][4] should become [3][4][2][1].
        // See the UUID Javadoc (and more specifically the high bits layout of a Leach-Salz UUID) to understand the
        // reasoning behind this bit twiddling in the first place (in the context of comparisons).
        return (input << 32)
               | ((input >>> 16) & 0xFFFF0000L)
               | (input >>> 48);
    }

    public ByteBuffer fromString(String source) throws MarshalException
    {
        ByteBuffer parsed = UUIDType.parse(source);
        if (parsed == null)
            throw new MarshalException(String.format("Unknown timeuuid representation: %s", source));
        if (parsed.remaining() == 16 && UUIDType.version(parsed) != 1)
            throw new MarshalException("TimeUUID supports only version 1 UUIDs");
        return parsed;
    }

    @Override
    public Term fromJSONObject(Object parsed) throws MarshalException
    {
        try
        {
            return new Constants.Value(fromString((String) parsed));
        }
        catch (ClassCastException exc)
        {
            throw new MarshalException(
                    String.format("Expected a string representation of a timeuuid, but got a %s: %s", parsed.getClass().getSimpleName(), parsed));
        }
    }

    public CQL3Type asCQL3Type()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Generate a v1 time UUID (UUIDGen.getTimeUUID()) for timeuuid columns.
  2. Validate client-side that uuid.version() == 1 before binding the parameter.
  3. Alter the column to type uuid if v4 UUIDs are the real intent.

Example fix

// before
UUID id = UUID.randomUUID();
// after
if (id.version() != 1) id = UUIDGen.getTimeUUID();
Defensive patterns

Strategy: type-guard

Validate before calling

if (uuid != null && uuid.version() != 1) uuid = UUIDGen.getTimeUUID();

Type guard

boolean isV1(java.util.UUID u) { return u != null && u.version() == 1; }

Try / catch

catch (MarshalException e) { log.warn("rejected non-v1 UUID for timeuuid column"); uuid = UUIDGen.getTimeUUID(); }

Prevention

When it happens

Trigger: Calling AbstractTimeUUIDType.fromString (directly or via fromJSONObject/CQL literals) with a valid UUID string whose version field is 2-5, e.g. a version-4 random UUID string.

Common situations: Passing UUID.randomUUID().toString() into a timeuuid column; mixed-up column types in schema migration; ORM code that shares one UUID generator for uuid and timeuuid columns.

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

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