apache/cassandra · error · InvalidRequestException

Function %s requires a map argument, but found argument %s o

Error message

Function %s requires a map argument, but found argument %s of type %s

What it means

Some native functions require their argument to be a map. FunctionParameter.validateType() checks the resolved argument type and throws this InvalidRequestException when the type is neither a MapType nor a UDT. It means the function was called with an argument of an incompatible (non-map) type.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/FunctionParameter.java:341

            {
                return "numeric_set_or_list";
            }
        };
    }

    /**
     * @return a function parameter definition that accepts values of type {@link MapType}, independently of the types
     * of the map keys and values.
     */
    static FunctionParameter anyMap()
    {
        return new FunctionParameter()
        {
            @Override
            public void validateType(FunctionName name, AssignmentTestable arg, AbstractType<?> argType)
            {
                if (!argType.isUDT() && !(argType instanceof MapType))
                    throw new InvalidRequestException(format("Function %s requires a map argument, " +
                                                             "but found argument %s of type %s",
                                                             name, arg, argType.asCQL3Type()));
            }

            @Override
            public String toString()
            {
                return "map";
            }
        };
    }

    /**
     * @param type the type of the vector elements
     * @return a function parameter definition that accepts values of type {@link VectorType} with elements of the
     * specified {@code type} and any dimensions.
     */
    static FunctionParameter vector(CQL3Type type)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Pass a map-typed argument, e.g. a map literal {'k':'v'} or a column defined as map<text,text>.
If passing a JSON string, convert it to a map via fromJson bound to a map type: fromJson('{"k":"v"}') used in an INSERT against a map column.
Alter the column or variable to map type if it was intended to be a map.
Alternatively store data as a UDT if that is accepted.

Example fix

// before
SELECT myFct(('a','b')) FROM t; -- tuple/list passed
// after
SELECT myFct({'a':'b'}) FROM t; -- map literal passed

Defensive patterns

Strategy: type-guard

Validate before calling

AbstractType<?> t = column.getType();
if (!(t instanceof MapType) && !t.isUDT()) throw new IllegalArgumentException("argument must be a map, got " + t.asCQL3Type());

Type guard

boolean isMapArg(AbstractType<?> t) { return t instanceof MapType || t.isUDT(); }

Try / catch

try { session.execute(q); } catch (InvalidRequestException e) { if (e.getMessage().contains("requires a map argument")) { /* supply a map literal or typed map column */ } else throw e; }

Prevention

Check function signatures before calling native functions
Use map literals {'k':'v'} rather than JSON strings
Keep schema types aligned with function expectations

When it happens

Trigger: Calling a map-parameter function (e.g. certain format or map-oriented native functions) with a list, set, text, int, or other non-map/UDT type as the map argument.

Common situations: Passing a JSON string instead of a map literal; supplying a list where a map was intended; column of wrong type used as the argument after schema changes.

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