hibernate/hibernate-orm · error · IllegalArgumentException

Unexpected frame mode: {frameClause.getChild(0)}

Error message

Unexpected frame mode: {frameClause.getChild(0)}

What it means

Error "Unexpected frame mode: {frameClause.getChild(0)}" thrown in hibernate/hibernate-orm.

Source

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

		final List<SqmSortSpecification> orderList =
				orderByClauseContext != null
						? visitOrderByClause( orderByClauseContext, false ).getSortSpecifications()
						: emptyList();

		final FrameMode mode;
		final FrameKind startKind;
		final SqmExpression<?> startExpression;
		final FrameKind endKind;
		final SqmExpression<?> endExpression;
		final FrameExclusion exclusion;
		final var frameClause = ctx.frameClause();
		if ( frameClause != null ) {
			final var symbol = ((TerminalNode) frameClause.getChild( 0 )).getSymbol();
			mode = switch ( symbol.getType() ) {
				case HqlParser.RANGE -> FrameMode.RANGE;
				case HqlParser.ROWS -> FrameMode.ROWS;
				case HqlParser.GROUPS -> FrameMode.GROUPS;
				default -> throw new IllegalArgumentException( "Unexpected frame mode: " + frameClause.getChild( 0 ) );
			};
			final int frameStartIndex;
			if ( frameClause.getChild( 1 ) instanceof TerminalNode ) {
				frameStartIndex = 2;
				endKind = getFrameKind( frameClause.getChild( 4 ) );
				endExpression = endKind == FrameKind.OFFSET_FOLLOWING || endKind == FrameKind.OFFSET_PRECEDING
						? (SqmExpression<?>) frameClause.getChild( 4 ).getChild( 0 ).accept( this )
						: null;
			}
			else {
				frameStartIndex = 1;
				endKind = FrameKind.CURRENT_ROW;
				endExpression = null;
			}
			startKind = getFrameKind( frameClause.getChild( frameStartIndex ) );
			startExpression =
					startKind == FrameKind.OFFSET_FOLLOWING || startKind == FrameKind.OFFSET_PRECEDING
							? (SqmExpression<?>) frameClause.getChild( frameStartIndex ).getChild( 0 ).accept( this )

View on GitHub (pinned to fad1729dce)

Solutions

1. The window frame mode is not one of RANGE, ROWS, or GROUPS. Correct the OVER clause frame specification.

When it happens

Trigger: The HQL parser produced a node the translator does not expect: Unexpected frame mode: <value>

Common situations: Usually an internal grammar edge case in window-frame or expression parsing; can surface with unusual but syntactically accepted HQL.

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