hibernate/hibernate-orm · error · IllegalStateException

Full join emulation null precedence index is missing for uni

Error message

Full join emulation null precedence index is missing for union query ordering

What it means

Error "Full join emulation null precedence index is missing for union query ordering" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/sql/ast/spi/FullJoinEmulation.java:548

	private void renderFullJoinEmulationSortExpression(
			SortSpecification sortSpecification,
			int sortSelectionIndex,
			int nullPrecedenceSelectionIndex) {
		if ( sortSpecification.isIgnoreCase() ) {
			throw new UnsupportedOperationException( "Full join emulation does not support ignore case ordering for union queries" );
		}
		if ( sortSelectionIndex < 0 ) {
			throw new UnsupportedOperationException( "Full join emulation requires order by expressions to be in the select list for union queries" );
		}

		final var sortOrder = sortSpecification.getSortOrder();
		final var nullPrecedence = resolveRenderedNullPrecedence( sortSpecification );
		final boolean renderNullPrecedence = nullPrecedence != null;
		final boolean supportsNullPrecedence = renderNullPrecedence && translator.getDialect().supportsNullPrecedence();
		if ( renderNullPrecedence && !supportsNullPrecedence ) {
			if ( nullPrecedenceSelectionIndex < 0 ) {
				throw new IllegalStateException( "Full join emulation null precedence index is missing for union query ordering" );
			}
			translator.appendSql( nullPrecedenceSelectionIndex + 1 );
			translator.appendSql( COMMA_SEPARATOR );
		}

		translator.appendSql( sortSelectionIndex + 1 );

		if ( sortOrder == SortDirection.DESCENDING ) {
			translator.appendSql( " desc" );
		}
		else if ( sortOrder == SortDirection.ASCENDING && renderNullPrecedence && supportsNullPrecedence ) {
			translator.appendSql( " asc" );
		}

		if ( renderNullPrecedence && supportsNullPrecedence ) {
			translator.appendSql( " nulls " );
			translator.appendSql( nullPrecedence == Nulls.LAST ? "last" : "first" );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Avoid explicit NULLS FIRST/NULLS LAST in the ORDER BY of a union query that requires full join emulation.
2. If null precedence is required, express it with a CASE expression in the select list and order by that item.
3. Use a database/dialect with native FULL JOIN support so the emulation path (and this limitation) is not used.

When it happens

Trigger: Full join emulation builds union ordering but the null-precedence index mapping for an order item is absent.

Common situations: Explicit NULLS FIRST/LAST on a union full join where the emulation could not map the precedence; remove explicit null precedence.

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