hibernate/hibernate-orm · error · IllegalQueryOperationException

Key-based pagination based on select list items is not yet s

Error message

Key-based pagination based on select list items is not yet supported

What it means

Error "Key-based pagination based on select list items is not yet supported" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/internal/KeyBasedPagination.java:100

			// ordering by an attribute of the returned entity
			final SortDirection direction = keyDefinition.get(i).direction();
			final SqmPath key = keyPaths.get(i);
			final Comparable keyValue = keyValues.get(i);
			final List<SqmPath<?>> previousKeys = keyPaths.subList(0, i);
			final SqmPredicate predicate = keyPredicate( key, keyValue, direction, previousKeys, keyValues, builder );
			restriction = restriction == null ? predicate : builder.or( restriction, predicate );
		}
		return restriction;
	}

	private static <R> JpaCompoundSelection<KeyedResult<R>> keySelection(
			List<Order<? super R>> keyDefinition,
			SqmFrom<?, ?> root, JpaSelection<?> selected,
			NodeBuilder builder) {
		final List<SqmPath<?>> items = new ArrayList<>();
		for ( Order<? super R> key : keyDefinition ) {
			if ( key.entityClass() == null ) {
				throw new IllegalQueryOperationException("Key-based pagination based on select list items is not yet supported");
			}
			else {
				if ( !key.entityClass().isAssignableFrom( selected.getJavaType() ) ) {
					throw new IllegalQueryOperationException("Select item was of wrong entity type");
				}
				// ordering by an attribute of the returned entity
				items.add( root.get( key.attributeName() ) );
			}
		}
		return keyedResultConstructor( selected, builder, items );
	}

	private static <R> JpaCompoundSelection<KeyedResult<R>> keyedResultConstructor(
			JpaSelection<?> selected, NodeBuilder builder, List<SqmPath<?>> newItems) {
		@SuppressWarnings({"rawtypes", "unchecked"})
		final Class<KeyedResult<R>> resultClass = (Class) KeyedResult.class;
		return builder.construct( resultClass, asList( selected, builder.construct(List.class, newItems ) ) );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Pagination over select-list items is not supported. Page over the entity root instead.

When it happens

Trigger: Key-based pagination preconditions are not met: Key-based pagination based on select list items is not yet supported

Common situations: Using key-based pagination on queries with no/multiple roots, multi-item select lists, non-entity select items, or pages containing null key values.

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