apache/cassandra · error · InvalidRequestException

Unexpected receiver type '%s'; only list and vector are expe

Error message

Unexpected receiver type '%s'; only list and vector are expected

What it means

An ArrayLiteral ([...], e.g. a bind marker [?] or array literal) can only be bound to a column whose type is a list or a vector. forReceiver() inspects the receiver column's unwrapped type and throws InvalidRequestException for any other receiver type (set, map, tuple, scalar, etc.).

Source

Thrown at src/java/org/apache/cassandra/cql3/terms/ArrayLiteral.java:49

 * so this class is meant to act as a proxy once the real type is known.
 */
public class ArrayLiteral extends Term.Raw
{
    private final List<Term.Raw> elements;

    public ArrayLiteral(List<Term.Raw> elements)
    {
        this.elements = elements;
    }

    private Term.Raw forReceiver(ColumnSpecification receiver)
    {
        AbstractType<?> type = receiver.type.unwrap();
        if (type instanceof VectorType)
            return new Vectors.Literal(elements);
        if (type instanceof ListType)
            return new Lists.Literal(elements);
        throw new InvalidRequestException(String.format("Unexpected receiver type '%s'; only list and vector are expected", type.asCQL3Type()));
    }

    @Override
    public Term prepare(String keyspace, ColumnSpecification receiver) throws InvalidRequestException
    {
        return forReceiver(receiver).prepare(keyspace, receiver);
    }

    @Override
    public TestResult testAssignment(String keyspace, ColumnSpecification receiver)
    {
        return forReceiver(receiver).testAssignment(keyspace, receiver);
    }

    @Override
    public AbstractType<?> getExactTypeIfKnown(String keyspace)
    {
        // without knowing the receiver, can't say if this is a ListType or a VectorType

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use the matching collection literal for the column type: {…} for sets/maps, (…) for tuples
Change the target column to a list or vector type if array semantics are required
Use a plain bind marker ? and pass the collection value in code

Example fix

// before
INSERT INTO t (s) VALUES ([1, 2, 3]);  -- s is a set<int>
// after
INSERT INTO t (s) VALUES ({1, 2, 3});  -- set literal

Defensive patterns

Strategy: type-guard

Validate before calling

function canUseArrayLiteral(colType) {
  const t = colType.replace(/^frozen<|>$/g, '');
  return t.startsWith('list<') || t.startsWith('vector<');
}

Type guard

function isArrayAssignable(receiver) {
  const t = receiver.type.unwrap();
  return t instanceof VectorType || t instanceof ListType;
}

Try / catch

try {
  session.execute(query, params);
} catch (e) {
  if (/Unexpected receiver type/.test(e.message)) { /* switch collection literal/bind syntax to match column type */ }
  else throw e;
}

Prevention

Match literal syntax to column type: [ ] lists, { } sets/maps, ( ) tuples
Check column types from table metadata before choosing bind syntax
Prefer generic bind markers (?) and pass typed values from the driver

When it happens

Trigger: Using `[?]`/`[...]` syntax against a column of unsupported type, e.g. `INSERT INTO t (s) VALUES ([?])` where s is a set or text; preparing array-literal terms in testAssignment against non-list/vector receivers.

Common situations: Mixing up [ ] (list) with { } (set/map) collection literals; generic query builders choosing array syntax for all collections; vectors vs lists confusion after version changes.

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/89c78ede8d98a80a. Report an issue: GitHub.