hibernate/hibernate-orm · error · SemanticException

'FILTER' clause is illegal for non-aggregate function: {func

Error message

'FILTER' clause is illegal for non-aggregate function: {functionName}

What it means

Error "'FILTER' clause is illegal for non-aggregate function: {functionName}" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java:4713

					true,
					null,
					StandardFunctionReturnTypeResolvers.invariant(
							resolveExpressibleTypeBasic( Object.class )
					),
					null,
					functionName,
					inferFunctionKind( ctx ),
					null,
					SqlAstNodeRenderingMode.DEFAULT
			);
		}
		else {
			if ( safeModeEnabled && "sql".equals( functionName ) ) {
				failIfSafeModeEnabled( safeModeEnabled, functionName, query );
			}
			final var functionKind = functionTemplate.getFunctionKind();
			if ( ctx.filterClause() != null && functionKind == FunctionKind.NORMAL ) {
				throw new SemanticException( "'FILTER' clause is illegal for non-aggregate function: "
						+ functionName,
						query );
			}
			if ( ctx.overClause() != null && functionKind == FunctionKind.NORMAL ) {
				throw new SemanticException( "'OVER' clause is illegal for non-aggregate function: "
						+ functionName,
						query );
			}
			if ( ctx.withinGroupClause() != null && functionKind == FunctionKind.NORMAL ) {
				throw new SemanticException( "'WITHIN' GROUP clause is illegal for non-aggregate function: "
						+ functionName,
						query );
			}
			if ( ctx.overClause() == null && functionKind == FunctionKind.WINDOW ) {
				throw new SemanticException( "'OVER' clause is mandatory for window-only function: "
						+ functionName,
						query );
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. FILTER is only legal on aggregate functions. Remove the FILTER clause, or use it with an aggregate function (count, sum, avg, min, max, ...).

When it happens

Trigger: An aggregate/window clause is applied to a function that does not accept it: 'FILTER' clause is illegal for non-aggregate function: <value>

Common situations: HQL queries that attach FILTER, OVER, WITHIN GROUP, RESPECT/IGNORE NULLS, or FROM FIRST/LAST to functions that are not aggregate or window functions, or omit a mandatory OVER/WITHIN GROUP clause.

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