apache/cassandra · error · MarshalException

Not enough bytes to read a

Error message

Not enough bytes to read a %s

What it means

CollectionType.validate() requires at least some bytes to represent a collection value; an empty (zero-length) value cannot encode any collection (its element count cannot be read). Cassandra throws this MarshalException when a collection column is validated against an empty byte buffer, since empty collections must be represented as null, not as empty bytes.

Solutions

1. Send null instead of an empty byte buffer for an empty collection value
2. Ensure the driver serializes collections with their element-count prefix (never 0 bytes total)
3. Check for custom code or tools writing raw cells that bypass collection serialization
4. If migrating data, rewrite legacy empty-collection cells as tombstones/null

Example fix

// before
ByteBuffer value = ByteBuffer.allocate(0);
// after
ByteBuffer value = null; // empty collections are represented as null

if (value == null || value.remaining() == 0) throw new IllegalArgumentException("collection value must be null or non-empty");

boolean isValidCollection(ByteBuffer v) { return v == null || v.remaining() > 0; }

When it happens

Trigger: Calling validate()/validate() paths (e.g. via UserType or internal validation on writes) with an empty ByteBuffer for a list/set/map column; constructing a collection value with accessor.isEmpty(value)==true.

Common situations: Application drivers or hand-rolled serialization writing a 0-length buffer instead of null for an empty collection; schema/data produced by older versions or external tools that encode empty collections differently; thrift-era leftovers.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Not enough bytes to read a + name
• The data cannot be deserialized as a + getCollectionName()
• cannot parse ' ' as hex bytes
• Invalid + charset + bytes + accessor.toHex(value)
• A local deletion time should not be negative

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

Appendix: source

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

        {
            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
    {
        if (isMultiCell())
            valueComparator().validateCellValue(cellValue, accessor);
        else
            super.validateCellValue(cellValue, accessor);
    }

    /**
     * Checks if this collection is Map.
     * @return <code>true</code> if this collection is a Map, <code>false</code> otherwise.
     */
    public boolean isMap()
    {

View on GitHub (pinned to 88fd0f6a0e)