apache/cassandra · error · IllegalArgumentException

Attempted to add float vector of dimension

Error message

Attempted to add float vector of dimension %d to %s

What it means

decomposeAsFloat(float[]) serializes a Java float array into the vector's binary form and requires the array length to equal the vector type's declared dimension. Throwing IllegalArgumentException when they differ prevents silently writing a vector with the wrong element count.

Solutions

1. Ensure the float array length matches the declared dimension of the VectorType
2. ALTER the table's vector column to the new dimension if the model changed
3. Check the embedding model's output size before calling decomposeAsFloat

Example fix

// before
float[] embedding = model.embed(text); // length 768
buffer = vectorType3.decomposeAsFloat(embedding); // dimension 3
// after
if (embedding.length == vectorType.getDimension())
    buffer = vectorType.decomposeAsFloat(embedding);

if (value == null || value.length != vectorType.getDimension())
    throw new IllegalArgumentException("expected dimension " + vectorType.getDimension() + ", got " + (value == null ? -1 : value.length));
ByteBuffer buf = vectorType.decomposeAsFloat(value);

try { buf = vt.decomposeAsFloat(arr); } catch (IllegalArgumentException e) { /* dimension drift: reload schema or resize */ }

When it happens

Trigger: Calling vectorType.decomposeAsFloat(new float[n]) where n != the dimension the VectorType was created with (e.g. dimension 3 type given a float[4]).

Common situations: Embedding/vector-search code where model output dimension changed (different embedding model version) but the table schema still declares the old dimension.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

• List had incorrect size: expected
• Required elements, but saw
• cannot parse ' ' as hex bytes
• Element at index is null (expected type ); given
• Expected a list, but got a

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

Appendix: source

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

    public ByteBuffer decompose(T... values)
    {
        return decompose(Arrays.asList(values));
    }

    public ByteBuffer decomposeAsFloat(float[] value)
    {
        return decomposeAsFloat(ByteBufferAccessor.instance, value);
    }

    public <V> V decomposeAsFloat(ValueAccessor<V> accessor, float[] value)
    {
        if (value == null)
            rejectNullOrEmptyValue();
        if (!(elementType instanceof FloatType))
            throw new IllegalStateException("Attempted to read as float, but element type is " + elementType.asCQL3Type());
        if (value.length != dimension)
            throw new IllegalArgumentException(String.format("Attempted to add float vector of dimension %d to %s", value.length, asCQL3Type()));
        // TODO : should we use TypeSizes to be consistent with other code?  Its the same value at the end of the day...
        V buffer = accessor.allocate(Float.BYTES * dimension);
        int offset = 0;
        for (int i = 0; i < dimension; i++)
        {
            accessor.putFloat(buffer, offset, value[i]);
            offset+= Float.BYTES;
        }
        return buffer;
    }

    public <V> V pack(List<V> elements, ValueAccessor<V> accessor)
    {
        return getSerializer().pack(elements, accessor);
    }

    @Override
    public List<ByteBuffer> filterSortAndValidateElements(List<ByteBuffer> buffers)

View on GitHub (pinned to 88fd0f6a0e)