apache/cassandra · error · MarshalException

Unknown timeuuid representation: %s

Error message

Unknown timeuuid representation: %s

What it means

fromString delegates to UUIDType.parse, which accepts a UUID string or (in some versions) date-based literal; when the string cannot be parsed as any known timeuuid representation, this MarshalException is thrown.

Source

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

               |  (input >>> 32);
    }

    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));
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Supply a canonical version-1 UUID string (8-4-4-4-12 hex with version nibble 1).
2. Use now() in CQL to let the server generate a timeuuid.
3. Validate/parse with UUID.fromString() client-side before sending, and check version()==1.

Example fix

// before
stmt.setString("id", "2024-01-01 00:00:00");
// after
stmt.setString("id", UUIDGen.getTimeUUID().toString());

boolean ok;
try { java.util.UUID.fromString(s); ok = true; } catch (IllegalArgumentException e) { ok = false; }

boolean isTimeUUIDLiteral(String s) { try { return java.util.UUID.fromString(s).version() == 1; } catch (Exception e) { return false; } }

catch (MarshalException e) { throw new IllegalArgumentException("Invalid timeuuid literal: " + source, e); }

When it happens

Trigger: Calling AbstractTimeUUIDType.fromString with a string that is not a valid UUID literal nor a recognized timeuuid literal (e.g. 'now()', a bare date string unsupported by this version, or a typo'd UUID).

Common situations: INSERT/UPDATE CQL with an invalid literal like '550e8400-e29b-41d4-a716-446655440000x'; using date strings for timeuuid on a Cassandra version that doesn't support them; application passing user input unvalidated.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• unable to make UUID from '%s'
• Unable to make UUID from '%s'
• Unable to parse node id string
• Invalid value for system property: expected integer value bu
• Invalid value for system property: expected long value but g

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