apache/cassandra · error · InvalidRequestException

Invalid vector literal for %s of type %s

Error message

Invalid vector literal for %s of type %s

What it means

Cassandra throws this InvalidRequestException in Vectors.Literal.prepare when a vector literal `[a, b, c]` is assigned to a receiver whose type is not a vector type. Vector literals are only valid for columns declared as vector<type, n>.

Source

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

        @Override
        public TestResult testAssignment(String keyspace, ColumnSpecification receiver)
        {
            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);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Confirm the column type is vector<K, N>; alter the schema or the statement.
  2. Use a list literal `json`-style or bind parameters for non-vector collections.
  3. If migrating, recreate the column as vector with the intended dimension.

Example fix

// before
CREATE TABLE t(id int PRIMARY KEY, embedding list<float>);
INSERT INTO t (id, embedding) VALUES (1, [0.1, 0.2]); // fails: not a vector
// after
ALTER TABLE t ADD embedding vector<float, 2>;
INSERT INTO t (id, embedding) VALUES (1, [0.1, 0.2]);
Defensive patterns

Strategy: validation

Validate before calling

if (!column.getType().unwrap().isVector())
    throw new IllegalArgumentException("Column " + column.getName() + " is not vector type; use proper literal");

Type guard

boolean isVectorColumn(ColumnSpecification c) { return c.type.unwrap().isVector(); }

Try / catch

try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("Invalid vector literal")) fixLiteralSyntax(); else throw e; }

Prevention

When it happens

Trigger: Using `[1,2,3]` for a list column, a set, or any non-vector receiver; schema changed the column from vector to list; misconfigured SAI/vector workload targeting the wrong column.

Common situations: Vector-search migrations where columns were expected to be vector<t, dim> but are lists; copy-paste between tables where one column is vector and the other is list.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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