apache/cassandra · error · InvalidRequestException

Ambiguous '%s' operation with args %s and %s: use type hint

Error message

Ambiguous '%s' operation with args %s and %s: use type hint to disambiguate, example '(int) ?'

What it means

When resolving a CQL operator (e.g. +, -) FunctionResolver found multiple compatible signatures. If the receiver (result type hint from surrounding context) doesn't disambiguate, Cassandra refuses to silently pick one and throws this message telling the developer to add an explicit type cast. This exists because operators like '+' are overloaded for int, long, float, decimal, date/duration combinations, and choosing the wrong one changes semantics.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/FunctionResolver.java:180

            throw invalidRequest("Invalid call to function %s, none of its type signatures match (known type signatures: %s)",
                                 name, format(candidates));
        }

        if (compatibles.size() > 1)
        {
            if (OperationFcts.isOperation(name))
            {
                if (receiverType != null && !containsMarkers(providedArgs))
                {
                    for (Function toTest : compatibles)
                    {
                        List<AbstractType<?>> argTypes = toTest.argTypes();
                        if (receiverType.equals(argTypes.get(0)) && receiverType.equals(argTypes.get(1)))
                            return toTest;
                    }
                }
                throw invalidRequest("Ambiguous '%s' operation with args %s and %s: use type hint to disambiguate, example '(int) ?'",
                                     OperationFcts.getOperator(name), providedArgs.get(0), providedArgs.get(1));
            }

            if (OperationFcts.isNegation(name))
                throw invalidRequest("Ambiguous negation: use type casts to disambiguate");

            throw invalidRequest("Ambiguous call to function %s (can be matched by following signatures: %s): use type casts to disambiguate",
                                 name, format(compatibles));
        }

        return compatibles.get(0);
    }

    /**
     * Checks if at least one of the specified arguments is a marker.
     *
     * @param args the arguments to check
     * @return {@code true} if if at least one of the specified arguments is a marker, {@code false} otherwise

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Add an explicit cast to one operand: (int) col or (double) col so exactly one signature matches
Wrap the expression in a CAST: SELECT CAST(a + b AS double) FROM t
Compare or assign the result against a typed target (e.g. a double column or literal) so the receiver type disambiguates
Reconsider column types so operands in arithmetic share the same type

Example fix

// before: ambiguous '+' between int and float
SELECT a + b FROM t;
// after
datastax session.execute("SELECT (double)a + b FROM t");

Defensive patterns

Strategy: validation

Validate before calling

function assertSameNumericType(a, b) { if (a !== b) throw new Error(`ambiguous '+' for ${a} and ${b}: add explicit cast`); }

Prevention

Always cast operands of arithmetic operators to a common type
Avoid mixing int/bigint/float/decimal columns in the same expression
Prefer CAST(... AS type) around operator results

When it happens

Trigger: A query like SELECT int_col + float_col FROM t (int and float overloads both applicable via coercion) with no receiver type to narrow it, e.g. no comparison against a typed literal or CAST that pins the result type.

Common situations: Arithmetic mixing int and bigint/float/decimal columns; date + duration vs date + time operations; users expecting Java-like numeric promotion which Cassandra deliberately does not auto-apply.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

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