apache/cassandra · error · MarshalException

Invalid + charset + bytes + accessor.toHex(value)

Error message

Invalid + charset + bytes + accessor.toHex(value)

What it means

AbstractTextSerializer.deserialize throws MarshalException when the byte buffer cannot be decoded with the column's charset (UTF-8 or ASCII). The bytes are not valid text for the declared type, so Cassandra refuses to return them as a string.

Solutions

1. Fix the schema: declare the column as blob if it stores binary data, or fix the writer to send valid charset-encoded strings.
2. For ascii columns that need non-ASCII characters, alter the column to text.
3. At the read site, catch MarshalException and inspect value bytes with ByteBufferUtil.bytesToHex to diagnose the encoding.
4. Re-encode offending data (rewrite the partition) after correcting the writer.

Example fix

// before (client writing raw bytes as text)
session.execute("INSERT INTO t (k, v) VALUES (?, ?)", k, someBinaryBytes); // MarshalException on read
// after
session.execute("INSERT INTO t (k, v) VALUES (?, ?)", k, new String(bytes, StandardCharsets.UTF_8));
// or ALTER TABLE t ALTER v TYPE blob;

boolean isValidText = Charset.forName(charset).newEncoder().canEncode(stringValue);

static boolean isAsciiSafe(String s) { return s.chars().allMatch(c -> c < 128); }

try { String s = textType.getSerializer().deserialize(value); } catch (MarshalException e) { logCorruptValue(value, e); }

When it happens

Trigger: Reading a column declared text/varchar/ascii whose stored bytes are not valid for the charset — e.g. blob data inserted via a BlobType column then read as text, arbitrary binary values written with wrong typing, or ascii columns containing bytes >127 (src/java/org/apache/cassandra/serializers/AbstractTextSerializer.java:46).

Common situations: Applications writing blobs into text columns via driver type coercion; importing data with sstableloader using a mismatched schema; latin-1/binary bytes written to a UTF-8 column; ascii columns receiving UTF-8 multibyte characters.

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

• Invalid ASCII character in string literal
• Invalid byte for ascii: + Byte.toString(b)
• Not enough bytes to read a + name
• Not enough bytes to read a
• The data cannot be deserialized as a + getCollectionName()

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

Appendix: source

Thrown at src/java/org/apache/cassandra/serializers/AbstractTextSerializer.java:46

public abstract class AbstractTextSerializer extends TypeSerializer<String>
{
    private final Charset charset;

    protected AbstractTextSerializer(Charset charset)
    {
        this.charset = charset;
    }

    public <V> String deserialize(V value, ValueAccessor<V> accessor)
    {
        try
        {
            return accessor.toString(value, charset);
        }
        catch (CharacterCodingException e)
        {
            throw new MarshalException("Invalid " + charset + " bytes " + accessor.toHex(value));
        }
    }

    public ByteBuffer serialize(String value)
    {
        return ByteBufferUtil.bytes(value, charset);
    }


    @Override
    public String toString(String value)
    {
        return value;
    }

    public Class<String> getType()
    {
        return String.class;

View on GitHub (pinned to 88fd0f6a0e)