hibernate/hibernate-orm · error · IllegalArgumentException

Query has multiple query roots

Error message

Query has multiple query roots

What it means

Error "Query has multiple query roots" thrown in hibernate/hibernate-orm.

Source

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

 * Manipulation of SQM query tree for key-based pagination.
 *
 * @author Gavin King
 */
public class KeyBasedPagination {

	public static <R> SqmSelectStatement<KeyedResult<R>> paginate(
			List<Order<? super R>> keyDefinition, List<Comparable<?>> keyValues,
			SqmSelectStatement<KeyedResult<R>> statement, NodeBuilder builder) {
		final SqmQuerySpec<?> querySpec = statement.getQuerySpec();
		final List<? extends JpaSelection<?>> items = querySpec.getSelectClause().getSelectionItems();
		final JpaSelection<?> selected = switch ( items.size() ) {
			case 0 -> {
				final List<SqmRoot<?>> sqmRoots = querySpec.getRootList();
				if ( sqmRoots == null || sqmRoots.isEmpty() ) {
					throw new IllegalArgumentException( "Query did not define any query roots" );
				}
				if ( sqmRoots.size() != 1 ) {
					throw new IllegalArgumentException( "Query has multiple query roots" );
				}
				yield sqmRoots.get( 0 );
			}
			case 1 -> items.get( 0 );
			default -> throw new IllegalQueryOperationException("Query has multiple items in the select list");
		};
		if ( selected instanceof SqmFrom<?, ?> root ) {
			statement.orderBy( keyDefinition.stream().map( order -> sortSpecification( statement, order ) )
					.collect( toList() ) );
			statement.select( keySelection( keyDefinition, root, selected, builder ) );
			if ( keyValues != null ) {
				final SqmPredicate restriction = keyRestriction( keyDefinition, keyValues, root, builder );
				final SqmPredicate queryWhere = querySpec.getRestriction();
				statement.where( queryWhere == null ? restriction : builder.and( queryWhere, restriction ) );
			}
			return statement;
		}
		else {

View on GitHub (pinned to fad1729dce)

Solutions

1. Key-based pagination supports only a single query root. Rewrite the query to select from one root entity.

When it happens

Trigger: The query structure does not meet the single-root/single-select-item requirement: Query has multiple query roots

Common situations: Key-based pagination or Specifications applied to queries with zero/multiple roots or multi-item select lists.

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