apache/cassandra · error · MarshalException

String representation of blob is missing 0x prefix: %s

Error message

String representation of blob is missing 0x prefix: %s

What it means

BytesType.fromJSONObject throws this when a JSON string value for a blob column does not start with the required '0x' prefix. JSON blob representations must be hex strings prefixed with 0x. Note the outer catch re-wraps MarshalExceptions, so this message may appear nested inside the 'not a valid blob representation' message.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/BytesType.java:66

    {
        try
        {
            return ByteBuffer.wrap(Hex.hexToBytes(source));
        }
        catch (NumberFormatException e)
        {
            throw new MarshalException(String.format("cannot parse '%s' as hex bytes", source), e);
        }
    }

    @Override
    public Term fromJSONObject(Object parsed) throws MarshalException
    {
        try
        {
            String parsedString = (String) parsed;
            if (!parsedString.startsWith("0x"))
                throw new MarshalException(String.format("String representation of blob is missing 0x prefix: %s", parsedString));

            return new Constants.Value(BytesType.instance.fromString(parsedString.substring(2)));
        }
        catch (ClassCastException | MarshalException exc)
        {
            throw new MarshalException(String.format("Value '%s' is not a valid blob representation: %s", parsed, exc.getMessage()));
        }
    }

    @Override
    public String toJSONString(ByteBuffer buffer, ProtocolVersion protocolVersion)
    {
        return "\"0x" + ByteBufferUtil.bytesToHex(buffer) + '"';
    }

    @Override
    public boolean isCompatibleWith(AbstractType<?> previous)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Prefix the hex string with 0x: {"b": "0xdeadbeef"}
2. Hex-encode binary data (not base64) and add the 0x prefix in the client
3. Convert base64 payloads to hex before JSON insert
4. Validate JSON blob fields for the 0x prefix before sending

Example fix

// before
INSERT INTO t JSON '{"b": "deadbeef"}';
// after
INSERT INTO t JSON '{"b": "0xdeadbeef"}';

if (!(v instanceof String) || !((String) v).startsWith("0x"))
    throw new IllegalArgumentException("Blob JSON value must be 0x-prefixed hex string");

boolean isBlobJson(Object v) { return v instanceof String && ((String) v).startsWith("0x") && ((String) v).length() % 2 == 0; }

try { Term t = bytesType.fromJSONObject(parsed); } catch (MarshalException e) { if (e.getMessage().contains("missing 0x prefix")) { /* prepend 0x and retry */ } else throw e; }

When it happens

Trigger: INSERT INTO t JSON '{"b": "deadbeef"}' (missing 0x); fromJson() with a plain hex string lacking 0x; JSON payloads containing base64-encoded blobs instead of hex.

Common situations: Client libraries that base64-encode binary by default (common in JSON ecosystems); hand-written JSON forgetting the prefix; docs/tooling showing bare hex without 0x.

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

• Value '%s' is not a valid blob representation: %s
• Expected an ascii string, but got a %s: %s
• Expected a boolean value, but got a %s: %s
• Expected a byte value, but got a %s: %s
• cannot parse '%s' as hex bytes

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