hibernate/hibernate-orm · error · IllegalArgumentException

Query did not define any query roots

Error message

Query did not define any query roots

What it means

Error "Query did not define any query roots" thrown in hibernate/hibernate-orm.

Source

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

import static org.hibernate.query.sqm.internal.SqmUtil.sortSpecification;

/**
 * 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 ) );
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. Key-based pagination requires a query with exactly one root. Add a from-clause root to the query.

When it happens

Trigger: A runtime precondition of the Hibernate query API is violated: Query did not define any query roots

Common situations: Application code or configuration calls the query API in a way that violates its documented contract; the interpolated values in the message identify the offending input.

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