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

UUIDType.fromJSONObject only accepts JSON strings containing a UUID representation; any other JSON type (number, boolean, array, object) fails the (String) cast and produces this MarshalException reporting the actual type.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/UUIDType.java:245

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

        return null;
    }

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

    static int version(ByteBuffer uuid)
    {
        return (uuid.get(6) & 0xf0) >> 4;
    }

    @Override
    public ByteBuffer getMaskedValue()
    {
        return MASKED_VALUE;
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the JSON value is a quoted string before parsing into a Term
2. Convert the object with String.valueOf or type-specific conversion first
3. Check the schema; if ids are numeric, use an integer type rather than uuid

Example fix

// before
term = uuidType.fromJSONObject(node.get("id")); // id is numeric
// after
Object id = node.get("id");
if (!(id instanceof String)) id = String.valueOf(id);
term = uuidType.fromJSONObject(id);

if (!(parsed instanceof String)) throw new IllegalArgumentException("UUID must be a JSON string, got: " + parsed);

boolean isUuidString(Object o) { return o instanceof String && isUuid((String) o); }

try { term = uuidType.fromJSONObject(parsed); } catch (MarshalException e) { throw new JsonMappingException("uuid field must be string"); }

When it happens

Trigger: Passing a parsed JSON number, boolean, list or map to UUIDType.fromJSONObject; e.g. fromJSONObject(42) or fromJSONObject(Map.of(...)).

Common situations: REST payloads delivering ids as integers; code generators mapping UUID columns to non-string JSON types; accidental passing of an already-parsed object instead of a string.

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

• Expected a string representation of a timeuuid, but got a %s
• Expected an ascii string, but got a %s: %s
• Expected a double value, but got a %s: %s
• Expected an empty string, but got: %s
• Expected a float value, but got a %s: %s

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