What causes "Could not resolve entity or correlation path '${name}'" in hibernate/hibernate-orm?

Fix the entity name spelling so it matches a mapped entity

hibernate/hibernate-orm · error · SemanticException

Could not resolve entity or correlation path '${name}'

Error message

Could not resolve entity or correlation path '${name}'

What it means

Thrown from resolveRootEntity when a from-clause name inside a query resolved neither to an entity nor to a correlation against an enclosing scope: the correlation consumption path did not produce a correlated root, so the name matches nothing usable and SemanticException 'Could not resolve entity or correlation path' is raised. In practice this fires when a subquery root references a misspelled entity or an outer alias that is not in scope.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java:2177

						alias,
						this
				);
				final int lastIdx = size - 1;
				for ( int i = 2; i != lastIdx; i += 2 ) {
					dotIdentifierConsumer.consumeIdentifier(
							entityNameParseTreeChildren.get( i ).getText(),
							false,
							false
					);
				}
				dotIdentifierConsumer.consumeIdentifier(
						entityNameParseTreeChildren.get( lastIdx ).getText(),
						false,
						true
				);
				return sqmCorrelation.getCorrelatedRoot();
			}
			throw new SemanticException( "Could not resolve entity or correlation path '" + name + "'", query );
		}
		final var cteStatement = findCteStatement( name );
		if ( cteStatement != null ) {
			final var root = new SqmCteRoot<>( cteStatement, alias);
			pathRegistry.register( root );
			return root;
		}
		throw new UnknownEntityException( "Could not resolve root entity '" + name + "'", name);
	}

	@Override
	public SqmCteStatement<?> findCteStatement(String name) {
		if ( currentPotentialRecursiveCte != null && name.equals( currentPotentialRecursiveCte.getName() ) ) {
			return (SqmCteStatement<?>) currentPotentialRecursiveCte;
		}
		return processingStateStack.findCurrentFirstWithParameter( name, SemanticQueryBuilder::matchCteStatement );
	}

View on GitHub (pinned to fad1729dce)

Solutions

Fix the entity name spelling so it matches a mapped entity
Correlate properly: reference the outer alias exactly as declared and only within its scope
If a path was intended, qualify it fully from an in-scope root

Example fix

// before
select e from Employee e where exists (select 1 from Departmetn d where d.id = e.deptId)

// after
select e from Employee e where exists (select 1 from Department d where d.id = e.deptId)

Defensive patterns

Strategy: validation

Validate before calling

static boolean rootResolvable(EntityManagerFactory emf, Set<String> cteNames, Set<String> outerAliases, String name) {
    boolean entity = emf.getMetamodel().getEntities().stream().anyMatch(e -> e.getName().equals(name));
    return entity || cteNames.contains(name) || outerAliases.contains(name);
}
// validate each subquery root against entities, declared CTE names, and in-scope outer aliases before building HQL

Try / catch

try {
    return em.createQuery(hql, Employee.class).getResultList();
} catch (org.hibernate.query.sqm.SemanticException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Could not resolve entity or correlation path")) {
        throw new IllegalArgumentException("Subquery root is neither an entity, CTE, nor in-scope outer alias: " + hql, e);
    }
    throw e;
}

Prevention

Keep subquery roots limited to mapped entity names or explicitly correlated outer aliases
When renaming outer aliases, grep nested subqueries for the old name
Prefer correlated paths ('select 1 from Employee e2 where e2.x = e.y') over duplicating roots

When it happens

Trigger: 'select e from Employee e where exists (select 1 from Departmetn d where d.id = e.deptId)' (typo, not an entity, not an outer alias); referencing an outer-query alias from a subquery nesting level where it is out of scope.

Common situations: Typos in entity names inside hand-written subqueries; renaming an outer alias without updating nested subqueries; refactoring that deepens subquery nesting beyond the alias's scope.

Related errors

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