prestodb/presto · error · SignatureMatchingException

Failed to find matching function signature for %s, matching

Error message

Failed to find matching function signature for %s, matching failures:

What it means

decideAndThrow is the terminal failure point of function signature matching. If exactly one underlying failure occurred it rethrows that original exception; otherwise it aggregates all per-candidate SignatureMatchingExceptions into one SignatureMatchingException listing every reason the function signature could not be matched. Unlike the AMBIGUOUS_FUNCTION_CALL errors, this fires when nothing matched, not when several things matched.

Source

Thrown at presto-main-base/src/main/java/com/facebook/presto/metadata/FunctionSignatureMatcher.java:365

                }
            }
        }
        return true;
    }

    /**
     * Decides which exception to throw based on the number of failed attempts.
     * If there's only one SemanticException, it throws that SemanticException directly.
     * If there are multiple SemanticExceptions, it throws the SignatureMatchingException.
     */
    public static void decideAndThrow(List<SemanticException> failedExceptions, String functionName)
            throws SemanticException
    {
        if (failedExceptions.size() == 1) {
            throw failedExceptions.get(0);
        }
        else {
            throw new SignatureMatchingException(format("Failed to find matching function signature for %s, matching failures: ", functionName), failedExceptions);
        }
    }

    static String constructFunctionNotFoundErrorMessage(QualifiedObjectName functionName, List<TypeSignatureProvider> parameterTypes, Collection<? extends SqlFunction> candidates)
    {
        String name = toConciseFunctionName(functionName);
        List<String> expectedParameters = new ArrayList<>();
        for (SqlFunction function : candidates) {
            expectedParameters.add(format("%s(%s) %s",
                    name,
                    Joiner.on(", ").join(function.getSignature().getArgumentTypes()),
                    Joiner.on(", ").join(function.getSignature().getTypeVariableConstraints())));
        }
        String parameters = Joiner.on(", ").join(parameterTypes);
        String message = format("Function %s not registered", name);
        if (!expectedParameters.isEmpty()) {
            String expected = Joiner.on(", ").join(expectedParameters);
            message = format("Unexpected parameters (%s) for function %s. Expected: %s", parameters, name, expected);

View on GitHub (pinned to 55bb57d202)

Solutions

Read the aggregated 'matching failures' list to see why each candidate was rejected
Fix argument count/types to match one candidate signature, adding CASTs as needed
Verify the function exists in the target catalog with the expected signature (SHOW FUNCTIONS)
If authoring the UDF, add an overload accepting the types being passed

Example fix

// before
SELECT date_diff('day', '2024-01-01', now()); -- no overload accepts varchar timestamp
// after
SELECT date_diff('day', DATE '2024-01-01', now());

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate arity and basic type compatibility before resolution:
if (candidates.stream().noneMatch(c -> c.getSignature().getArgumentTypes().size() == args.size())) {
    throw new IllegalStateException("Wrong argument count for " + functionName);
}

Try / catch

try { applicable = identifyApplicableFunctions(candidates, args); }
catch (SignatureMatchingException e) { /* inspect e.getFailures() and report each reason */ }

Prevention

Match argument count and types to a documented overload (SHOW FUNCTIONS / docs)
CAST arguments to the exact declared types of the intended overload
Don't pass NULL untyped — use CAST(NULL AS <type>)
When authoring UDFs, add overloads for common type combinations

When it happens

Trigger: identifyApplicableFunctions tried all candidate signatures for a function name and each failed for a (possibly different) reason — type mismatches, wrong arity, etc. — producing multiple failedExceptions.

Common situations: Calling a function with the wrong number of arguments across all overloads; arguments whose types no overload accepts; connector-qualified functions not found with parameters matching any candidate; complex calls where each overload fails differently so only the aggregate message appears.

Related errors

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/61c3447cbf8b3dc6. Report an issue: GitHub.