apache/cassandra · error · MarshalException

cannot parse '%s' as hex bytes

Error message

cannot parse '%s' as hex bytes

What it means

CollectionType.fromString throws 'cannot parse ... as hex bytes' when the source string for a collection-typed value cannot be converted via ByteBufferUtil.hexToBytes. Collection literals are normally parsed by the grammar, but this path handles string→bytes conversion for collection inputs and fails on non-hex or odd-length input.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/CollectionType.java:135

    public ByteBuffer decompose(T value)
    {
        return super.decompose(value);
    }

    public <V> String getString(V value, ValueAccessor<V> accessor)
    {
        return BytesType.instance.getString(value, accessor);
    }

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

    public boolean isCollection()
    {
        return true;
    }

    @Override
    public <V> void validate(V value, ValueAccessor<V> accessor) throws MarshalException
    {
        if (accessor.isEmpty(value))
            throw new MarshalException("Not enough bytes to read a " + toLowerCaseLocalized(kind.name()));
        super.validate(value, accessor);
    }

    @Override
    public <V> void validateCellValue(V cellValue, ValueAccessor<V> accessor) throws MarshalException

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the input is valid even-length hex before it reaches the collection parser
2. Hex-encode each element (bytesToHex per element) when constructing literals
3. Use proper CQL collection literal syntax ([1,2,3], {1:'a'}, {'k','v'}) instead of raw hex strings via fromString
4. For blob elements inside collections, encode each as valid hex

Example fix

// before
Term t = listType.fromString("abc"); // odd-length hex
// after
Term t = listType.fromString("0abc"); // valid even-length hex

public static void assertCollectionHex(String s) {
    if (s == null || s.isEmpty() || s.length() % 2 != 0 || !s.matches("[0-9a-fA-F]+"))
        throw new IllegalArgumentException("Invalid hex for collection: " + s);
}

When it happens

Trigger: Binding a non-hex string where the collection's key/value serializer expects hex bytes; programmatic Term construction for collection columns with malformed hex (e.g. 'zz' or odd-length 'abc'); corrupt string-encoded collection input routed through fromString.

Common situations: Custom drivers/tools building collection Terms from raw strings; replaying exported CQL where blob elements lost their hex encoding; frozen collections containing blobs hydrated from logs; JSON-style array strings pasted directly as collection input.

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

• cannot parse '%s' as hex bytes
• Invalid operation (%s) for set column %s
• Invalid null value for element selection on <columnName>
• Invalid ASCII character in string literal: %s
• Expected an ascii string, but got a %s: %s

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