hibernate/hibernate-orm · error · FunctionArgumentException

Function %s() requires between %d and %d arguments, but %d a

Error message

Function %s() requires between %d and %d arguments, but %d arguments given

What it means

Hibernate 6 validates every HQL/criteria function call while the query is parsed. StandardArgumentsValidators.between(minNumOfArgs, maxNumOfArgs) creates the validator used by most registered SqmFunctionDescriptors, and it throws this FunctionArgumentException as soon as the parsed argument list falls outside [min, max]. The query never reaches SQL generation; the failure surfaces from EntityManager.createQuery(...) or the criteria compile step.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sqm/produce/function/StandardArgumentsValidators.java:191

						sig.append(", ");
					}
					sig.append("arg").append(i);
				}
				sig.append("])");
				return sig.toString();
			}
		};
	}

	public static ArgumentsValidator between(int minNumOfArgs, int maxNumOfArgs) {
		return new ArgumentsValidator() {
			@Override
			public void validate(
					List<? extends SqmTypedNode<?>> arguments,
					String functionName,
					BindingContext bindingContext) {
				if ( arguments.size() < minNumOfArgs || arguments.size() > maxNumOfArgs ) {
					throw new FunctionArgumentException(
							String.format(
									Locale.ROOT,
									"Function %s() requires between %d and %d arguments, but %d arguments given",
									functionName,
									minNumOfArgs,
									maxNumOfArgs,
									arguments.size()
							)
					);
				}
			}

			@Override
			public String getSignature() {
				final var sig = new StringBuilder("(");
				for (int i=0; i<maxNumOfArgs; i++) {
					if (i==minNumOfArgs) {
						sig.append("[");

View on GitHub (pinned to fad1729dce)

Solutions

Fix the HQL call to pass the number of arguments the function declares - the message states the accepted min/max and the count actually passed.
If the function is your own (dialect/FunctionContributor), correct the between(min,max) bounds or use Parameters.variadic(...) for genuinely optional or repeating arguments.
If the function is native to your database only, register a proper descriptor or call it through native SQL instead of HQL.
Inspect the function in force via QueryEngine.getSqmFunctionRegistry() to confirm the arity of your Hibernate version.

Example fix

// before - substring requires 2 or 3 arguments
select p from Person p where substring(p.name) = 'x'

// after
select p from Person p where substring(p.name, 1, 4) = 'x'

Defensive patterns

Strategy: try-catch

Try / catch

try {
    TypedQuery<Person> q = em.createQuery(hql, Person.class);
} catch (org.hibernate.query.sqm.produce.function.FunctionArgumentException e) {
    // parse-time failure; the message states function name, min/max arity, and actual count
    throw new BadRequestException("Invalid function call: " + e.getMessage(), e);
}

Prevention

Unit-test every custom HQL string against the exact Hibernate version you ship; arity enforcement differs across versions.
Keep custom function registrations (dialect/FunctionContributor) under integration test covering both min and max arity.
Log the offending HQL whenever this exception fires so the call site is identifiable in production.

When it happens

Trigger: Calling an HQL function with the wrong arity, e.g. substring(p.name) (requires 2-3), locate(p.name) (requires 2-3), or a custom function registered with between(1,2) but invoked with 3 arguments: select my_func(a, b, c). The validator runs at query creation time, not at execution.

Common situations: Hand-written HQL with a typo'd argument list; signatures tightened during Hibernate 5.x to 6.x migration so previously tolerated calls now fail; a dialect or FunctionContributor registering a descriptor with wrong between() bounds; pasting native SQL with optional arguments into HQL.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/39c4520a0903cb8b. Report an issue: GitHub.