apache/cassandra · error · InvalidRequestException

Invalid vector literal for

Error message

Invalid vector literal for %s of type %s; expected %d elements, but given %d

What it means

Thrown when a vector literal's element count does not equal the fixed dimension declared in the vector type (vector<type, N>). Vector types have a fixed dimension, so a literal with fewer or more elements is rejected at prepare time.

Solutions

1. Supply exactly `dimension` elements matching vector<t, N>.
2. ALTER TABLE ... to change the column to a vector type with the new dimension if the model changed.
3. Validate embedding lengths in client code before issuing the statement.

Example fix

// before
INSERT INTO t (id, embedding) VALUES (1, [0.1, 0.2]); // embedding is vector<float, 3>
// after
INSERT INTO t (id, embedding) VALUES (1, [0.1, 0.2, 0.3]);

VectorType<?> vt = (VectorType<?>) column.getType().unwrap();
if (elements.size() != vt.dimension)
    throw new IllegalArgumentException("Expected " + vt.dimension + " elements, got " + elements.size());

try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("expected") && e.getMessage().contains("elements")) padOrTrimEmbedding(); else throw e; }

When it happens

Trigger: `INSERT INTO t (embedding) VALUES [0.1, 0.2]` where embedding is vector<float, 3>; client-side embedding model dimension changed; truncation or padding of embeddings before sending.

Common situations: Switching embedding models (e.g. 384-dim to 768-dim) without altering the column dimension; batch pipelines with mixed-length embeddings; off-by-one in generating embeddings.

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

• ANN ordering is only supported on float vector indexes
• Function requires a vector argument, but found argument of…
• Invalid vector literal for
• Invalid vector literal for
• Required elements, but saw

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/terms/Vectors.java:124

            if (!receiver.type.isVector())
                return AssignmentTestable.TestResult.NOT_ASSIGNABLE;
            VectorType<?> type = (VectorType<?>) receiver.type;
            if (elements.size() != type.dimension)
                return AssignmentTestable.TestResult.NOT_ASSIGNABLE;
            ColumnSpecification valueSpec = valueSpecOf(receiver);
            return AssignmentTestable.TestResult.testAll(receiver.ksName, valueSpec, elements);
        }

        @Override
        public Term prepare(String keyspace, ColumnSpecification receiver) throws InvalidRequestException
        {
            AbstractType<?> unwrapped = receiver.type.unwrap();

            if (!unwrapped.isVector())
                throw new InvalidRequestException(String.format("Invalid vector literal for %s of type %s", receiver.name, receiver.type.asCQL3Type()));
            VectorType<?> type = (VectorType<?>) unwrapped;
            if (elements.size() != type.dimension)
                throw new InvalidRequestException(String.format("Invalid vector literal for %s of type %s; expected %d elements, but given %d", receiver.name, receiver.type.asCQL3Type(), type.dimension, elements.size()));

            ColumnSpecification valueSpec = valueSpecOf(receiver);
            List<Term> values = new ArrayList<>(elements.size());
            boolean allTerminal = true;
            for (Term.Raw rt : elements)
            {
                if (!rt.testAssignment(keyspace, valueSpec).isAssignable())
                    throw new InvalidRequestException(String.format("Invalid vector literal for %s: value %s is not of type %s", receiver.name, rt, valueSpec.type.asCQL3Type()));

                Term t = rt.prepare(keyspace, valueSpec);

                if (t instanceof Term.NonTerminal)
                    allTerminal = false;

                values.add(t);
            }
            MultiElements.DelayedValue value = new MultiElements.DelayedValue(type, values);
            return allTerminal ? value.bind(FunctionContext.NONE) : value;

View on GitHub (pinned to 88fd0f6a0e)