hibernate/hibernate-orm · error · IllegalStateException

Cannot augment a subquery

Error message

Cannot augment a subquery

What it means

Error "Cannot augment a subquery" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/specification/internal/SelectionSpecificationImpl.java:166

		return specifications;
	}

	@Nonnull
	@Override
	public SelectionSpecification<T> restrict(@Nonnull Restriction<? super T> restriction) {
		specifications.add( (sqmStatement, root) -> {
			final var sqmPredicate = SqmUtil.restriction( sqmStatement, resultType, restriction );
			sqmStatement.getQuerySpec().applyPredicate( sqmPredicate );
		} );
		return this;
	}

	@Nonnull
	@Override
	public SelectionSpecification<T> augment(@Nonnull Augmentation<T> augmentation) {
		specifications.add( (sqmStatement, root) -> {
			if ( !( sqmStatement instanceof SqmSelectStatement<T> selectStatement ) ) {
				throw new IllegalStateException( "Cannot augment a subquery" );
			}
			augmentation.augment( sqmStatement.nodeBuilder(), selectStatement, root );
		} );
		return this;
	}

	@Nonnull
	@Override
	public SelectionSpecification<T> fetch(@Nonnull Path<T, ?> fetchPath) {
		specifications.add( (sqmStatement, root) -> fetchPath.fetch( root ) );
		return this;
	}

	@Nonnull
	@Override
	public SelectionSpecification<T> sort(@Nonnull Order<? super T> order) {
		specifications.add( (sqmStatement, root) -> addOrder( order, sqmStatement ) );
		return this;

View on GitHub (pinned to fad1729dce)

Solutions

1. A subquery cannot be augmented by a specification. Apply the specification to the outer query.

When it happens

Trigger: A runtime precondition of the Hibernate query API is violated: Cannot augment a subquery

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/1c6fcd9fad52b417. Report an issue: GitHub.