{"record":{"id":"3306f689398ea9b9","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-entity-or-correlation-path-na","errorCode":null,"errorMessage":"Could not resolve entity or correlation path '${name}'","messagePattern":"Could not resolve entity or correlation path '(.+?)'","errorType":"exception","errorClass":"SemanticException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java","lineNumber":2177,"sourceCode":"\t\t\t\t\t\talias,\n\t\t\t\t\t\tthis\n\t\t\t\t);\n\t\t\t\tfinal int lastIdx = size - 1;\n\t\t\t\tfor ( int i = 2; i != lastIdx; i += 2 ) {\n\t\t\t\t\tdotIdentifierConsumer.consumeIdentifier(\n\t\t\t\t\t\t\tentityNameParseTreeChildren.get( i ).getText(),\n\t\t\t\t\t\t\tfalse,\n\t\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tdotIdentifierConsumer.consumeIdentifier(\n\t\t\t\t\t\tentityNameParseTreeChildren.get( lastIdx ).getText(),\n\t\t\t\t\t\tfalse,\n\t\t\t\t\t\ttrue\n\t\t\t\t);\n\t\t\t\treturn sqmCorrelation.getCorrelatedRoot();\n\t\t\t}\n\t\t\tthrow new SemanticException( \"Could not resolve entity or correlation path '\" + name + \"'\", query );\n\t\t}\n\t\tfinal var cteStatement = findCteStatement( name );\n\t\tif ( cteStatement != null ) {\n\t\t\tfinal var root = new SqmCteRoot<>( cteStatement, alias);\n\t\t\tpathRegistry.register( root );\n\t\t\treturn root;\n\t\t}\n\t\tthrow new UnknownEntityException( \"Could not resolve root entity '\" + name + \"'\", name);\n\t}\n\n\t@Override\n\tpublic SqmCteStatement<?> findCteStatement(String name) {\n\t\tif ( currentPotentialRecursiveCte != null && name.equals( currentPotentialRecursiveCte.getName() ) ) {\n\t\t\treturn (SqmCteStatement<?>) currentPotentialRecursiveCte;\n\t\t}\n\t\treturn processingStateStack.findCurrentFirstWithParameter( name, SemanticQueryBuilder::matchCteStatement );\n\t}\n","sourceCodeStart":2159,"sourceCodeEnd":2195,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java#L2159-L2195","documentation":"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.","triggerScenarios":"'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.","commonSituations":"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.","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"],"exampleFix":"// before\nselect e from Employee e where exists (select 1 from Departmetn d where d.id = e.deptId)\n\n// after\nselect e from Employee e where exists (select 1 from Department d where d.id = e.deptId)","handlingStrategy":"validation","validationCode":"static boolean rootResolvable(EntityManagerFactory emf, Set<String> cteNames, Set<String> outerAliases, String name) {\n    boolean entity = emf.getMetamodel().getEntities().stream().anyMatch(e -> e.getName().equals(name));\n    return entity || cteNames.contains(name) || outerAliases.contains(name);\n}\n// validate each subquery root against entities, declared CTE names, and in-scope outer aliases before building HQL","typeGuard":null,"tryCatchPattern":"try {\n    return em.createQuery(hql, Employee.class).getResultList();\n} catch (org.hibernate.query.sqm.SemanticException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Could not resolve entity or correlation path\")) {\n        throw new IllegalArgumentException(\"Subquery root is neither an entity, CTE, nor in-scope outer alias: \" + hql, e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["hql","subquery","correlation","entity-resolution","hibernate"],"backgroundTag":"unknown-entity-or-alias","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}