What causes "Expected a string representation of a uuid, but got a %s: %s" in apache/cassandra?

Serialize the UUID as a quoted string in the JSON payload.

apache/cassandra · error · MarshalException

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

Error message

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

What it means

LexicalUUIDType.fromJSONObject expects the parsed JSON value to be a String containing a UUID representation. If the JSON value is a number, object, array, or other non-string type, the cast (String) parsed fails and a MarshalException is thrown with this message.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/LexicalUUIDType.java:134

        {
            return decompose(UUID.fromString(source));
        }
        catch (IllegalArgumentException e)
        {
            throw new MarshalException(String.format("unable to make UUID from '%s'", source), e);
        }
    }

    @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 uuid, but got a %s: %s", parsed.getClass().getSimpleName(), parsed));
        }
    }

    @Override
    public TypeSerializer<UUID> getSerializer()
    {
        return SERIALIZER;
    }

    @Override
    public ArgumentDeserializer getArgumentDeserializer()
    {
        return ARGUMENT_DESERIALIZER;
    }

    @Override
    public ByteBuffer getMaskedValue()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Serialize the UUID as a quoted string in the JSON payload.
Convert the value to a string client-side before sending (e.g. String.valueOf or JSON.stringify of the id).
Fix the producer's serialization config so UUIDs map to JSON strings.

Example fix

// before
{"id": 12345}
// after
{"id": "550e8400-e29b-41d4-a716-446655440000"}

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(jsonValue instanceof String)) throw new IllegalArgumentException("uuid column expects a JSON string, got: " + jsonValue.getClass().getSimpleName());

Type guard

boolean isJsonUuid(Object o) { return o instanceof String && UUID_RE.matcher((String) o).matches(); }

Try / catch

try { return lexicalType.fromJSONObject(parsed); } catch (MarshalException e) { throw new BadRequestException("uuid field must be a string: " + e.getMessage()); }

Prevention

Serialize UUIDs as JSON strings in all producers.
Add a schema (e.g. JSON Schema) requiring type string for uuid fields.
Test payloads against the Cassandra column types before deployment.

When it happens

Trigger: Using fromJSONObject (JSON INSERT / fromJson()) with a uuid column whose JSON value is a number, boolean, object, or array instead of a string.

Common situations: JSON documents where the UUID was serialized as a number or nested object by the producer; JavaScript clients serializing UUIDs without quotes; schema drift between producer and Cassandra table.

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/13f71d8e8424a7f1. Report an issue: GitHub.