hibernate/hibernate-orm · error · FunctionArgumentException

Function argument [%s] at specified position [%d] in call ar

Error message

Function argument [%s] at specified position [%d] in call arguments was not typed as an allowable function return type

What it means

extractArgumentValuedMapping(arguments, position) is the SQL-AST-level counterpart used during function rendering: it takes the rendered argument expression at the given 1-based position and requires its expression type to be a BasicValuedMapping (a basic, JDBC-mappable value). If the argument expression resolves to anything else - null, an embedded, entity, or plural mapping - it throws FunctionArgumentException during query interpretation.

Source

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

//						)
//				);
//			}
//
//			return basicType.getJdbcMapping();
//		}
//	}

	public static BasicValuedMapping extractArgumentValuedMapping(List<? extends SqlAstNode> arguments, int position) {
		final SqlAstNode specifiedArgument = arguments.get( position-1 );
		final var specifiedArgType =
				specifiedArgument instanceof Expression expression
						? expression.getExpressionType()
						: null;
		if ( specifiedArgType instanceof BasicValuedMapping basicValuedMapping ) {
			return basicValuedMapping;
		}
		else {
			throw new FunctionArgumentException(
					String.format(
							Locale.ROOT,
							"Function argument [%s] at specified position [%d] in call arguments was not typed as an allowable function return type",
							specifiedArgument,
							position
					)
			);
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Dereference to a basic attribute before calling the function: my_func(e.address.zip) or my_func(e.assoc.id).
Verify the position argument (it is 1-based) actually points at the basic-valued argument.
If optional arguments can reach the helper, filter them out of the list before extraction.
Prefer invariant return types for functions whose arguments are not guaranteed to stay basic.

Example fix

// before - e.address is an embeddable, not basic-valued
select my_func(e.address) from Employee e

// after - target a basic attribute inside it
select my_func(e.address.zip) from Employee e

Defensive patterns

Strategy: validation

Validate before calling

static boolean isBasicValued(SqmTypedNode<?> node) {
    return node.getNodeType() instanceof BasicType;
}

Try / catch

try {
    query.getResultList();
} catch (org.hibernate.query.sqm.produce.function.FunctionArgumentException e) {
    // message names the offending argument and its position
    throw new IllegalArgumentException(e.getMessage(), e);
}

Prevention

Route only basic attributes into functions that extract BasicValuedMappings; dereference embeddables and associations first.
Re-verify argument positions (1-based) whenever a custom function's pattern or signature is edited.
Cover each function with a rendering test against the actual mapped entity model.

When it happens

Trigger: A custom function whose rendering path (or set-returning resolver) calls extractArgumentValuedMapping on an argument that is not basic-valued: passing an embeddable or association path (e.g. e.address) into a function that only handles basic columns.

Common situations: Functions that worked on simple columns then applied to embedded/association attributes; a version upgrade where an argument that used to be basic became a mapped component; an off-by-one in the position after editing the function signature.

Related errors

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