apache/cassandra · error · InvalidRequestException

Invalid tuple literal for %s: component %d is not of type %s

Error message

Invalid tuple literal for %s: component %d is not of type %s

What it means

Cassandra throws this when an individual component of a tuple literal cannot be assigned to the declared type of the corresponding tuple component. During validation, each element's type is checked via AssignmentTestable.testAssignment against the component spec (componentSpecOf(receiver, i)); if the value's type is incompatible with the tuple's i-th component type, an InvalidRequestException naming the zero-based component index and expected type is thrown.

Source

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

    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());
        }
    }

    /**
     * Tests that the tuple with the specified elements can be assigned to the specified column.
     *
     * @param receiver the receiving column
     * @param elements the tuple elements
     */
    public static AssignmentTestable.TestResult testTupleAssignment(ColumnSpecification receiver,
                                                                    List<? extends AssignmentTestable> elements)
    {
        try
        {
            validateTupleAssignableTo(receiver, elements);
            return AssignmentTestable.TestResult.WEAKLY_ASSIGNABLE;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Read the expected component type from the error message (e.g. component 2 must be int) and fix the literal or binding at that position to match.
  2. Check the column's declared tuple type with `DESCRIBE TABLE` and reorder values so each matches its positional component type.
  3. Add explicit literals/casts in CQL (e.g. use 2 instead of '2', toTimestamp(now()) for timestamps) since Cassandra does not implicitly coerce between types.
  4. In application code, validate each value's type against the tuple component types before building the statement, or use the driver's typed tuple type (e.g. TupleType.newValue with correctly typed fields).

Example fix

// before: component 0 of tuple<int, text> gets a string
INSERT INTO t (k, c) VALUES (1, ('42', 'a'));

// after: component types match the declaration
INSERT INTO t (k, c) VALUES (1, (42, 'a'));
Defensive patterns

Strategy: validation

Validate before calling

TupleType tt = (TupleType) column.getType();
for (int i = 0; i < values.size(); i++) {
    DataType expected = tt.getComponentTypes().get(i);
    if (!expected.accepts(values.get(i)))
        throw new IllegalArgumentException(
            String.format("component %d of %s must be %s", i, column.getName(), expected));
}

Prevention

When it happens

Trigger: Inserting a tuple literal whose i-th value has a mismatched type, e.g. `c = ('a', 2)` for `tuple<int, text>` (component 0 is text, expected int); using a string literal where a numeric/timestamp/boolean component is required; relying on implicit conversions Cassandra does not perform; binding parameters whose Java types the driver maps to a non-assignable CQL type.

Common situations: Swapping the order of tuple components in application code; passing a stringly-typed value ('2024-01-01') into a timestamp or int component without an explicit cast; driver version changes that alter how a Java type binds to a CQL type; constructing tuples programmatically from heterogeneous config values.

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