{"record":{"id":"59437647d6079673","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-root-entity-name","errorCode":null,"errorMessage":"Could not resolve root entity '${name}'","messagePattern":"Could not resolve root entity '(.+?)'","errorType":"exception","errorClass":"UnknownEntityException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java","lineNumber":2185,"sourceCode":"\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\n\tprivate static SqmCteStatement<?> matchCteStatement(SqmCreationProcessingState state, String n) {\n\t\treturn state.getProcessingQuery() instanceof SqmCteContainer container\n\t\t\t\t? container.getCteStatement( n )\n\t\t\t\t: null;\n\t}\n\n\t@Override\n\tpublic SqmRoot<?> visitRootSubquery(HqlParser.RootSubqueryContext ctx) {","sourceCodeStart":2167,"sourceCodeEnd":2203,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java#L2167-L2203","documentation":"The final fallback of root resolution: the from-clause name is not a mapped entity, not resolvable as a correlation, and no CTE with that name exists, so UnknownEntityException 'Could not resolve root entity' is thrown. This is the classic 'entity not mapped' error for the primary from-clause root.","triggerScenarios":"'select e from EMPLOYEE e' where the mapped name is 'Employee'; wrong case; quoted-identifier mismatch; entity missing from the persistence unit; a CTE referenced under a different name than declared in the WITH clause.","commonSituations":"Native SQL habits (table names instead of entity names); class renamed or moved without updating queries; persistence.xml/persistenceUnitRoot/packagesToScan missing the entity package; case-sensitive mismatches after moving between databases or naming strategies.","solutions":["Use the exact mapped entity name (check @Entity(name=...) and metamodel entity names, mind case)","Ensure the entity class is scanned by the persistence unit","For CTE roots, match the name declared in the WITH clause exactly","If the name collides, use the fully qualified class name if registered, or disambiguate with @Entity(name=...)"],"exampleFix":"// before\nselect e from EMPLOYEE e\n\n// after\nselect e from Employee e","handlingStrategy":"validation","validationCode":"static boolean isMappedEntityName(EntityManagerFactory emf, String name) {\n    for (jakarta.persistence.metamodel.EntityType<?> e : emf.getMetamodel().getEntities()) {\n        if (e.getName().equals(name)) return true;\n    }\n    return false;\n}\n\n// validate every from-clause root before creating the query\nif (!isMappedEntityName(emf, rootName)) throw new IllegalArgumentException(\"Entity not mapped: \" + rootName);","typeGuard":"static boolean isUnknownEntity(Throwable t) {\n    return t instanceof org.hibernate.query.sqm.UnknownEntityException;\n}","tryCatchPattern":"try {\n    return em.createQuery(hql, Object[].class).getResultList();\n} catch (org.hibernate.query.sqm.UnknownEntityException e) {\n    throw new IllegalArgumentException(\"From-clause root is not a mapped entity: \" + e.getEntityName()\n            + \" - accepted names are in em.getMetamodel().getEntities()\", e);\n}","preventionTips":["Smoke-test all stored HQL strings with createQuery at startup or in CI","When entities are renamed, add a mapping test that fails on stale entity names in queries","Remember from-clause roots take entity names, never table names"],"tags":["hql","entity-resolution","from-clause","hibernate","metamodel"],"backgroundTag":"unknown-entity-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}