apache/cassandra · error · InvalidRequestException

Unknown function

Error message

Unknown function '%s'

What it means

When preparing a function call in the SELECT clause, FunctionResolver.get found no native or user function matching the name and argument types. The code translates a null resolver result into this InvalidRequestException.

Solutions

  1. Correct the function name (check DESCRIBE FUNCTIONS / system_schema.functions)
  2. Qualify with the keyspace: SELECT ks.fn(col) FROM ...
  3. Create the UDF/UDA in the current keyspace before running the query

Example fix

// before
SELECT avrg(x) FROM t;
// after
SELECT avg(x) FROM t;
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check availability
Row r = session.execute("SELECT function_name FROM system_schema.functions WHERE keyspace_name=?", ks).one();

Try / catch

try { stmt = session.prepare(sql); }
catch (InvalidRequestException e) {
  if (e.getMessage().contains("Unknown function")) { /* register/qualify the function and retry */ }
  throw e;
}

Prevention

When it happens

Trigger: SELECT unknown_fn(col) FROM t — the function name is misspelled, defined in another keyspace, or arg types match no overload.

Common situations: Typo in aggregate/native function names, calling a UDA/UDF created in a different keyspace without qualification, or a function dropped before the query runs.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/selection/Selectable.java:453

                FunctionName name = functionName;
                // COUNT(x) is equivalent to COUNT(*) for any non-null term x (since count(x) don't care about its
                // argument outside of check for nullness) and for backward compatibilty we want to support COUNT(1),
                // but we actually have COUNT(x) method for every existing (simple) input types so currently COUNT(1)
                // will throw as ambiguous (since 1 works for any type). So we have to special case COUNT.
                if (functionName.equalsNativeFunction(FunctionName.nativeFunction("count"))
                        && preparedArgs.size() == 1
                        && (preparedArgs.get(0) instanceof WithTerm)
                        && (((WithTerm)preparedArgs.get(0)).rawTerm instanceof Constants.Literal))
                {
                    // Note that 'null' isn't a Constants.Literal
                    name = AggregateFcts.countRowsFunction.name();
                    preparedArgs = Collections.emptyList();
                }
                Function fun = FunctionResolver.get(table.keyspace, name, preparedArgs, table.keyspace, table.name, null, UserFunctions.getCurrentUserFunctions(name, table.keyspace));

                if (fun == null)
                    throw new InvalidRequestException(String.format("Unknown function '%s'", functionName));

                if (fun.returnType() == null)
                    throw new InvalidRequestException(String.format("Unknown function %s called in selection clause", functionName));

                return new WithFunction(fun, preparedArgs);
            }
        }
    }

    public static class WithCast implements Selectable
    {
        private final CQL3Type type;
        private final Selectable arg;

        public WithCast(Selectable arg, CQL3Type type)
        {
            this.arg = arg;
            this.type = type;

View on GitHub (pinned to 88fd0f6a0e)