apache/cassandra · error · MarshalException

Expected a byte value, but got a %s: %s

Error message

Expected a byte value, but got a %s: %s

What it means

ByteType.fromJSONObject throws this when a JSON value for a byte column is neither a JSON string nor a JSON number. Only strings (parsed via fromString) and numbers are accepted; booleans, objects, arrays etc. are rejected with the class simple name and value in the message.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/ByteType.java:92

        try
        {
            b = Byte.parseByte(source);
        }
        catch (Exception e)
        {
            throw new MarshalException(String.format("Unable to make byte from '%s'", source), e);
        }

        return decompose(b);
    }

    public Term fromJSONObject(Object parsed) throws MarshalException
    {
        if (parsed instanceof String || parsed instanceof Number)
            return new Constants.Value(fromString(String.valueOf(parsed)));

        throw new MarshalException(String.format(
                "Expected a byte value, but got a %s: %s", parsed.getClass().getSimpleName(), parsed));
    }

    @Override
    public String toJSONString(ByteBuffer buffer, ProtocolVersion protocolVersion)
    {
        return getSerializer().deserialize(buffer).toString();
    }

    @Override
    public CQL3Type asCQL3Type()
    {
        return CQL3Type.Native.TINYINT;
    }

    @Override
    public TypeSerializer<Byte> getSerializer()
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Send a JSON number: {"v": 42} (or a quoted numeric string)
2. Coerce the value to a number in application code before JSON insert
3. Fix the client model so byte columns map to numeric fields
4. Validate JSON against schema types before sending

Example fix

// before
INSERT INTO t JSON '{"v": true}';
// after
INSERT INTO t JSON '{"v": 42}';

if (!(v instanceof Number || v instanceof String)) throw new IllegalArgumentException("byte JSON value must be number or numeric string");

boolean isByteJson(Object v) { return v instanceof Number || v instanceof String; }

try { Term t = byteType.fromJSONObject(parsed); } catch (MarshalException e) { if (e.getMessage().startsWith("Expected a byte value")) { /* fix payload type to number */ } else throw e; }

When it happens

Trigger: INSERT INTO t JSON '{"v": true}' where v is a byte column; fromJson() with a boolean or object argument targeting a byte column; Term.fromJSONObject receiving e.g. Boolean or Map.

Common situations: JSON payloads where a byte field is accidentally a boolean flag; serializers emitting nested objects for numeric columns; schema drift between client models and Cassandra schema.

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 an ascii string, but got a %s: %s
• Expected a boolean value, but got a %s: %s
• Unable to make byte from '%s'
• String representation of blob is missing 0x prefix: %s
• Value '%s' is not a valid blob representation: %s

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