apache/cassandra · error · MarshalException

Value '%s' is not a valid blob representation: %s

Error message

Value '%s' is not a valid blob representation: %s

What it means

BytesType.fromJSONObject wraps ClassCastException and any nested MarshalException into this generic 'not a valid blob representation' error. It fires when the JSON value is not a String at all (cast fails), or when the string fails 0x-prefix or hex parsing; the original message is appended after the colon.

Source

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

        {
            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)
    {
        // Both asciiType and utf8Type really use bytes comparison and
        // bytesType validate everything, so it is compatible with the former.
        return this == previous || previous == AsciiType.instance || previous == UTF8Type.instance;
    }

    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Send a plain 0x-prefixed hex string: {"b": "0x00ff"}
  2. Convert the value to a hex String in application code before JSON insert
  3. Read the nested message after 'representation:' to find the root cause (prefix vs hex)
  4. Align client serialization so binary columns map to hex strings

Example fix

// before
INSERT INTO t JSON '{"b": {"$binary": "3q2+7w=="}}';
// after
INSERT INTO t JSON '{"b": "0xdeadbeef"}';
Defensive patterns

Strategy: try-catch

Validate before calling

if (parsed == null || !(parsed instanceof String))
    throw new IllegalArgumentException("Blob JSON value must be a string");

Type guard

boolean isBlobString(Object v) { return v instanceof String; }

Try / catch

try { Term t = bytesType.fromJSONObject(parsed); } catch (MarshalException e) { if (e.getMessage().startsWith("Value '")) { /* inspect nested cause, fix payload type/prefix, retry */ } else throw e; }

Prevention

When it happens

Trigger: INSERT INTO t JSON '{"b": 123}' (number, not string); extended-JSON object payloads like {"$binary": ...}; a string failing hex parse inside fromString (nested 'cannot parse ... as hex bytes' message).

Common situations: MongoDB-style extended-JSON binary payloads; JSON serializers that emit numbers or objects for binary columns; schema drift where a former text column is now blob and payloads still send unquoted values.

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/0ed28e59e044880b. Report an issue: GitHub.