apache/cassandra · error · InvalidRequestException

Invalid tuple type literal for %s of type %s

Error message

Invalid tuple type literal for %s of type %s

What it means

validateTupleAssignableTo first checks that the receiver's type is a tuple type at all; if a tuple literal is supplied for a column whose type is not a tuple (after unwrap), this error is thrown. It is the arity/element checks' guard clause, invoked from testTupleAssignment.

Source

Thrown at src/java/org/apache/cassandra/cql3/terms/Tuples.java:182

            if (type == null)
                return null;
            types.add(type);
        }
        return new TupleType(types);
    }

    /**
     * Checks if the tuple with the specified elements can be assigned to the specified column.
     *
     * @param receiver the receiving column
     * @param elements the tuple elements
     * @throws InvalidRequestException if the tuple cannot be assigned to the specified column.
     */
    public static void validateTupleAssignableTo(ColumnSpecification receiver,
                                                 List<? extends AssignmentTestable> elements)
    {
        if (!checkIfTupleType(receiver.type))
            throw invalidRequest("Invalid tuple type literal for %s of type %s", receiver.name, receiver.type.asCQL3Type());

        TupleType tt = getTupleType(receiver.type);
        for (int i = 0; i < elements.size(); i++)
        {
            if (i >= tt.size())
            {
                throw invalidRequest("Invalid tuple literal for %s: too many elements. Type %s expects %d but got %d",
                                     receiver.name, tt.asCQL3Type(), tt.size(), elements.size());
            }

            AssignmentTestable value = elements.get(i);
            ColumnSpecification spec = componentSpecOf(receiver, i);
            if (!value.testAssignment(receiver.ksName, spec).isAssignable())
                throw invalidRequest("Invalid tuple literal for %s: component %d is not of type %s",
                                     receiver.name, i, spec.type.asCQL3Type());
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Match the literal to the column type: use a UDT literal {field: value} for user-defined types, list/set/map literals for collections.
2. Confirm the column type via DESCRIBE TABLE and correct the statement.
3. If a tuple was intended, alter the column to the appropriate tuple type first.

Example fix

// before (address is a UDT)
INSERT INTO t (id, address) VALUES (1, ('Main St', 42));
// after
INSERT INTO t (id, address) VALUES (1, {street: 'Main St', num: 42});

if (!colType.startsWith("tuple<")) throw new IllegalArgumentException("tuple literal requires a tuple column, got " + colType);

boolean acceptsTupleLiteral(String columnType) { return columnType != null && columnType.startsWith("tuple<"); }

When it happens

Trigger: Using a tuple literal (a, b, c) for a column of a non-tuple type (e.g. text, list<..>, UDT), either in INSERT/UPDATE values or comparisons during assignment testing.

Common situations: Column type changed from tuple to something else; confusing UDTs with tuple syntax (UDTs use {field: value}); driver code emitting tuple literals for json/UDT columns.

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 tuple literal for %s: component %d is not of type %s
• Invalid timestamp value: <tval>
• Invalid TTL value: <tval>
• Not enough bytes to read size of %dth component
• Not enough bytes to read %dth component

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