apache/cassandra · error · MarshalException

Expected a string representation of a timeuuid, but got a %s

Error message

Expected a string representation of a timeuuid, but got a %s: %s

What it means

fromJSONObject expects the JSON-parsed object to be a String containing a timeuuid literal; when it is any other JSON type, the ClassCastException is caught and rethrown as this MarshalException naming the offending type.

Source

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

    {
        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()
    {
        return CQL3Type.Native.TIMEUUID;
    }

    @Override
    public ByteBuffer decomposeUntyped(Object value)
    {
        if (value instanceof UUID)
            return UUIDSerializer.instance.serialize((UUID) value);
        if (value instanceof TimeUUID)
            return TimeUUID.Serializer.instance.serialize((TimeUUID) value);
        return super.decomposeUntyped(value);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Send the timeuuid as a JSON string literal, not a number or object.
Coerce/validate in application code: if (!(parsed instanceof String)) convert or reject before the call.
Fix the producer's serialization schema so timeuuid fields are strings.

Example fix

// before
Term t = type.fromJSONObject(jsonNode.numericValue());
// after
Term t = type.fromJSONObject(jsonNode.textValue()); // e.g. "d2177dd0-eaa2-11e3-949e-0800200c9a66"

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(parsed instanceof String)) throw new IllegalArgumentException("timeuuid JSON field must be a string");

Type guard

String asTimeString(Object o) { return (o instanceof String) ? (String) o : null; }

Try / catch

catch (MarshalException e) { throw new BadRequestException("timeuuid must be a JSON string: " + e.getMessage()); }

Prevention

Enforce string typing for UUID fields in your JSON schema (OpenAPI type: string, format: uuid).
Validate incoming JSON payloads against the schema before binding.
Convert numeric timestamps to timeuuids explicitly with UUIDGen.getTimeUUID(bytes, millis) if needed.

When it happens

Trigger: Calling AbstractTimeUUIDType.fromJSONObject with a non-String (Integer, Map, List, Boolean, etc.) — e.g. JSON '{"col": 12345}' against a timeuuid column.

Common situations: JSON-based ingestion APIs where the client sends a number or object for a timeuuid field; schema drift between producer and Cassandra table; generated client code passing parsed JSON values directly.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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