apache/cassandra · error · MarshalException

null is not supported inside vectors

Error message

null is not supported inside vectors

What it means

When marshalling/validating a vector value, Cassandra checks each element buffer and rejects any null (or element buffer whose element type reports isNull). Vectors are fixed-size collections and null elements are not representable, so MarshalException is thrown.

Source

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

        return filterSortAndValidateElements(buffers, ByteBufferUtil.UNSET_BYTE_BUFFER, ByteBufferAccessor.instance);
    }

    @Override
    public List<byte[]> filterSortAndValidateElementsFromArrays(List<byte[]> buffers)
    {
        return filterSortAndValidateElements(buffers, ByteArrayUtil.UNSET_BYTE_ARRAY, ByteArrayAccessor.instance);
    }

    public <V> List<V> filterSortAndValidateElements(List<V> buffers, V unsetValue, ValueAccessor<V> valueAccessor)
    {
        // We only filter and validate for this type.
        if (buffers == null)
            return null;

        for (V buffer : buffers)
        {
            if (buffer == null || elementType.isNull(buffer, valueAccessor))
                throw new MarshalException("null is not supported inside vectors");

            if (buffer == unsetValue)
                throw new InvalidRequestException("unset is not supported inside vectors");

            elementType.validate(buffer, valueAccessor);
        }
        return buffers;
    }

    @Override
    public <V> ByteSource asComparableBytes(ValueAccessor<V> accessor, V value, ByteComparable.Version version)
    {
        if (isNull(value, accessor))
            return null;
        ByteSource[] srcs = new ByteSource[dimension];
        List<V> split = unpack(value, accessor);
        for (int i = 0; i < dimension; i++)
            srcs[i] = elementType.asComparableBytes(accessor, split.get(i), version);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Replace null elements with type-appropriate defaults before binding
2. Filter out or reject rows with null elements before constructing the vector
3. Store a sentinel value (e.g. 0.0f for float vectors) instead of null
4. Use try-catch around marshal if nulls are possible and handle gracefully

Example fix

// before
List<Integer> values = Arrays.asList(1, null, 3);
ByteBuffer buf = vectorType.decompose(values);
// after
List<Integer> values = Arrays.asList(1, 0, 3); // no nulls
ByteBuffer buf = vectorType.decompose(values);

boolean hasNull = values == null || values.stream().anyMatch(Objects::isNull);
if (hasNull) throw new IllegalArgumentException("null elements not allowed in vector");

boolean hasNoNulls = values != null && values.stream().noneMatch(Objects::isNull);

try { buf = vt.decompose(values); } catch (MarshalException e) { /* handle null elements */ }

When it happens

Trigger: Binding a Java List/array containing null elements for a vector column (e.g. List<ByteBuffer> with a null entry, or Integer[] with nulls for vector<int>), then inserting or validating via filterSortAndValidateElements.

Common situations: Application code building vector values from data that may contain nulls (missing embeddings, optional fields); deserialization paths feeding null entries into vector composition.

Related errors

• Element at index %d is null (expected type %s); given %s
• unset is not supported inside vectors
• Invalid null element in list
• REVOKE operation is not supported by AllowAllAuthorizer
• %s is not a valid data resource name

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