apache/cassandra · error · MarshalException

cannot parse '%s' as hex bytes

Error message

cannot parse '%s' as hex bytes

What it means

VectorType.fromString treats its input as a hex-encoded byte string. If the string cannot be parsed as hex, MarshalException is thrown wrapping the NumberFormatException. For vectors this generic string parsing path is rarely the intended entry point — elements are usually provided as literals or JSON.

Source

Thrown at src/java/org/apache/cassandra/db/marshal/VectorType.java:280

    }

    // vector of nested types is hard to parse, so fall back to bytes string matching ListType
    @Override
    public <V> String getString(V value, ValueAccessor<V> accessor)
    {
        return BytesType.instance.getString(value, accessor);
    }

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

    @Override
    public List<AbstractType<?>> subTypes()
    {
        return Collections.singletonList(elementType);
    }

    @Override
    public String toJSONString(ByteBuffer buffer, ProtocolVersion protocolVersion)
    {
        return toJSONString(buffer, ByteBufferAccessor.instance, protocolVersion);
    }

    @Override
    public <V> String toJSONString(V value, ValueAccessor<V> accessor, ProtocolVersion protocolVersion)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pass a valid hex-encoded string (even length, 0-9a-fA-F only)
2. Use elementType-appropriate parsing (e.g. fromJSONObject with a JSON list) instead of fromString for vector literals
3. Pre-clean/validate the string with a hex regex before calling fromString

Example fix

// before
ByteBuffer buf = vectorType.fromString("1,2,3");
// after
Term term = vectorType.fromJSONObject(Arrays.asList(1, 2, 3));

if (source == null || !source.matches("[0-9a-fA-F]*") || source.length() % 2 != 0)
    throw new IllegalArgumentException("not valid hex: " + source);

try { buf = vt.fromString(source); } catch (MarshalException e) { /* fall back to JSON parsing */ }

When it happens

Trigger: Calling vectorType.fromString("not-hex") or passing a string containing non-hex characters (or odd-length hex) directly to fromString.

Common situations: Test code or tooling building vector values from strings; cqlsh/scripting paths passing raw strings where hex-encoded binary is expected.

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 32-bits int value from "%s"
• Cannot parse timestamp value from "%s"
• Cannot parse date value from "%s"
• Cannot parse time value from "%s"
• Cannot parse collection value from "%s", at character %d exp

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