apache/cassandra · error · MarshalException

unable to make UUID from '%s'

Error message

unable to make UUID from '%s'

What it means

LexicalUUIDType.fromString parses a string into a UUID. If the string is not a valid textual UUID representation, UUID.fromString throws IllegalArgumentException, which is wrapped in a MarshalException with this message.

Source

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

        // Lexical UUIDs are stored as just two signed longs. The decoding of these longs flips their sign bit back, so
        // they can directly be used for constructing the original UUID.
        return UUIDType.makeUuidBytes(accessor, hiBits, loBits);
    }

    public ByteBuffer fromString(String source) throws MarshalException
    {
        // Return an empty ByteBuffer for an empty string.
        if (source.isEmpty())
            return ByteBufferUtil.EMPTY_BYTE_BUFFER;

        try
        {
            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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Ensure the string is a valid UUID in canonical 8-4-4-4-12 hex format before passing it (e.g. UUID.fromString as a pre-check in the client).
  2. Use UUID.randomUUID() or another generator rather than hand-constructing the string.
  3. If accepting arbitrary IDs, validate with a regex or try/catch and return a user-friendly validation error before sending the query.

Example fix

// before
String id = row.get("id"); // e.g. "12345"
insert.bind(id);
// after
UUID uuid = UUID.fromString(id); // throws IllegalArgumentException early if malformed
insert.bind(uuid);
Defensive patterns

Strategy: try-catch

Validate before calling

private static final Pattern UUID_RE = Pattern.compile("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$");
boolean valid = source != null && UUID_RE.matcher(source).matches();

Type guard

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

Try / catch

try { term = lexicalType.fromString(source); } catch (MarshalException e) { throw new BadRequestException("Invalid UUID: " + source); }

Prevention

When it happens

Trigger: Passing a non-UUID string to fromString, e.g. via INSERT/UPDATE with a string literal for a uuid column, or fromJSONObject delegating to fromString with user text like 'abc' or '123' (missing dashes/length, invalid hex characters).

Common situations: Application inserts hand-built string values into uuid columns; JSON payloads contain string IDs generated by another system that are not canonical UUID format; typos or truncated UUIDs.

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

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