apache/cassandra · error · InvalidRequestException

Invalid reference type %s (%s) for "%s" of type %s

Error message

Invalid reference type %s (%s) for "%s" of type %s

What it means

Thrown when preparing a RowDataReference in a transaction: the referenced column's type is not assignable to the receiver the data reference was resolved against. testAssignment fails and the exception reports the column type, column name, receiver name, and receiver type.

Source

Thrown at src/java/org/apache/cassandra/cql3/transactions/RowDataReference.java:366

        {
            return prepare(keyspace, receiver, tupleName, column, elementPath, fieldPath);
        }

        public RowDataReference prepareAsReceiver()
        {
            checkResolved();
            return new RowDataReference(tuple.toString(), tupleName, column, table, elementPath, fieldPath);
        }

        private RowDataReference prepare(String keyspace,
                                         ColumnSpecification receiver,
                                         int txnDataName,
                                         ColumnMetadata column,
                                         Term elementPath,
                                         CellPath fieldPath)
        {
            if (!testAssignment(keyspace, receiver).isAssignable())
                throw new InvalidRequestException(String.format("Invalid reference type %s (%s) for \"%s\" of type %s",
                                                                column.type, column.name, receiver.name, receiver.type.asCQL3Type()));

            return new RowDataReference(tuple.toString(), txnDataName, column, table, elementPath, fieldPath);
        }

        @Override
        public String getText()
        {
            StringBuilder text = new StringBuilder(tuple.toString());

            if (selected != null)
                text.append('.').append(selected);

            if (fieldOrElement != null)
            {
                if (fieldOrElement instanceof Term.Raw)
                {
                    Term.Raw element = (Term.Raw) fieldOrElement;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Align the referenced column type with the receiver (cast or use a column of the correct type).
2. Check the transaction statement's conditions and targets against the referenced column types.
3. Re-validate prepared transactions after schema alterations.

Example fix

// before
SELECT balance FROM data WHERE ...; // used where text expected
IF updated.text_col = data.balance ... // balance is int, text_col is text
// after
IF updated.num_col = data.balance ... // matching int types

if (!referencedColumn.type.testAssignment(keyspace, receiver).isAssignable())
    throw new IllegalArgumentException("Reference " + referencedColumn.name + " not assignable to " + receiver.name);

try { session.execute(txnStmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("Invalid reference type")) alignReferenceTypes(); else throw e; }

When it happens

Trigger: A transaction data reference (e.g. `data.ref` used in a condition or update) whose column type does not match what the consuming receiver expects, e.g. referencing an int column where a text value is required in the transaction statement.

Common situations: Type drift between the referenced column and the transaction's target/condition after a schema change; building transaction references programmatically with mismatched types.

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

• Invalid timestamp value: <tval>
• Invalid TTL value: <tval>
• Error decoding JSON value for %s: %s
• Invalid operation (%s) for non-UDT column %s
• Invalid operation (%s) for non-numeric and non-text type %s

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