apache/cassandra · error · IllegalArgumentException

Receiving type does not match

Error message

Receiving type {receiveType} does not match {type}

What it means

TxnReference.toByteBuffer() validates that the receiver's type matches the referenced field's type (accounting for frozen collections and reversed clustering keys) before extracting raw bytes. If the receiving type differs from the reference's type, the reference cannot be safely applied, and an IllegalArgumentException is thrown.

Solutions

  1. Fix transaction construction so the receiver's unwrapped type equals the reference's unwrapped type
  2. If a schema change altered the column type, rebuild/retry the affected transactions against the new schema
  3. Check frozen-collection handling: ensure freeze()/unwrap() is applied symmetrically on both sides
  4. Verify the field selection type (getFieldSelectionType) matches the actual column type

Example fix

// before
TxnReference ref = new TxnReference(tableId, receiverColumn, referenceColumn /* type mismatch after ALTER */);
// after
AbstractType<?> expected = receiverColumn.isFrozenCollection() ? receiverColumn.freeze().unwrap() : receiverColumn.unwrap();
Invariants.requireArgument(expected.equals(referenceColumn.unwrap()), "Receiver type %s must match reference type %s", expected, referenceColumn.unwrap());
Defensive patterns

Strategy: validation

Validate before calling

AbstractType<?> recv = receiver.isFrozenCollection() ? receiver.freeze().unwrap() : receiver.unwrap();
AbstractType<?> ref  = referenceType.isFrozenCollection() ? referenceType.freeze().unwrap() : referenceType.unwrap();
if (!recv.equals(ref)) throw new IllegalArgumentException("Receiver type " + recv + " != reference type " + ref);

Type guard

static boolean typesMatch(AbstractType<?> receiver, AbstractType<?> reference) {
    return unwrapCompatible(receiver).equals(unwrapCompatible(reference));
}

Try / catch

try { ByteBuffer buf = ref.toByteBuffer(); }
catch (IllegalArgumentException e) { /* type mismatch — rebind the txn against current schema */ }

Prevention

When it happens

Trigger: Constructing a transaction reference (TxnReference) whose receiver column type differs from the referenced value's type — e.g. applying a write computed against one column type into a receiver column of a different (unwrapped) type, or referencing a key/clustering value with the wrong type after schema changes.

Common situations: Schema migrations that changed a column's type while transactions referencing the old type are in flight; bugs in transaction-building code that mismatch receiver and reference types; frozen collection handling errors.

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/accord/txn/TxnReference.java:442

            // TODO: confirm all references can be satisfied as part of the txn condition
            AbstractType<?> type = column().type;

            // Modify the type we'll check if the reference is to a collection element.
            if (selectsPath())
            {
                if (type.isCollection())
                {
                    CollectionType<?> collectionType = (CollectionType<?>) type;
                    type = collectionType.kind == SET ? collectionType.nameComparator() : collectionType.valueComparator();
                }
                else if (type.isUDT())
                    type = getFieldSelectionType();
            }

            // Account for frozen collection and reversed clustering key references:
            AbstractType<?> receiveType = type.isFrozenCollection() ? receiver.freeze().unwrap() : receiver.unwrap();
            if (!(receiveType == type.unwrap()))
                throw new IllegalArgumentException("Receiving type " + receiveType + " does not match " + type.unwrap());

            if (column().isPartitionKey())
                return getPartitionKey(data);
            else if (column().isClusteringColumn())
                return getClusteringKey(data);

            ColumnData columnData = getColumnData(data);

            if (columnData == null)
                return null;

            if (selectsComplex())
            {
                ComplexColumnData complex = (ComplexColumnData) columnData;

                if (type instanceof CollectionType)
                {
                    CollectionType<?> col = (CollectionType<?>) type;

View on GitHub (pinned to 88fd0f6a0e)