{"record":{"id":"253c0d23962f8eff","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-target-entity-entityname","errorCode":null,"errorMessage":"Could not resolve target entity '${entityName}'","messagePattern":"Could not resolve target entity '(.+?)'","errorType":"exception","errorClass":"UnknownEntityException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java","lineNumber":2036,"sourceCode":"\t\t\t\t? child.getText()\n\t\t\t\t: visitNakedIdentifier( (HqlParser.NakedIdentifierContext) child );\n\t}\n\n\t@Override\n\tpublic String visitNakedIdentifier(HqlParser.NakedIdentifierContext ctx) {\n\t\tfinal var node = (TerminalNode) ctx.getChild( 0 );\n\t\tfinal String text = node.getText();\n\t\treturn node.getSymbol().getType() == QUOTED_IDENTIFIER\n\t\t\t\t? unquoteIdentifier( text )\n\t\t\t\t: text;\n\t}\n\n\t@Override\n\tpublic EntityDomainType<?> visitEntityName(HqlParser.EntityNameContext parserEntityName) {\n\t\tfinal String entityName = getEntityName( parserEntityName );\n\t\tfinal var entityReference = getJpaMetamodel().getHqlEntityReference( entityName );\n\t\tif ( entityReference == null ) {\n\t\t\tthrow new UnknownEntityException( \"Could not resolve target entity '\" + entityName + \"'\", entityName );\n\t\t}\n\t\tcheckFQNEntityNameJpaComplianceViolationIfNeeded( entityName, entityReference );\n\t\tif ( entityReference instanceof SqmPolymorphicRootDescriptor<?>\n\t\t\t\t&& getCreationOptions().useStrictJpaCompliance() ) {\n\t\t\tthrow new StrictJpaComplianceViolation(\n\t\t\t\t\t\"Encountered the use of a non entity name [\" + entityName + \"], \" +\n\t\t\t\t\t\t\t\"but strict JPQL compliance was requested which doesn't allow this\",\n\t\t\t\t\tStrictJpaComplianceViolation.Type.NON_ENTITY_NAME\n\t\t\t);\n\t\t}\n\t\treturn entityReference;\n\t}\n\n\t@Override\n\tpublic SqmFromClause visitFromClause(HqlParser.FromClauseContext parserFromClause) {\n\t\tfinal var roots = parserFromClause.entityWithJoins();\n\t\tfinal var fromClause = new SqmFromClause( roots.size() );\n","sourceCodeStart":2018,"sourceCodeEnd":2054,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java#L2018-L2054","documentation":"visitEntityName resolves a name that must denote an entity (treat(x as N), type comparisons, entity joins, etc.) through JpaMetamodel.getHqlEntityReference. A null result means no entity or registered polymorphic reference answers to that name, so UnknownEntityException is thrown carrying the unresolved name.","triggerScenarios":"'select treat(o as SpecialOrder) from Order o' when SpecialOrder is not a mapped entity; 'where type(a) = MissingEntity'; using a DTO, interface or enum class name in a position that requires an entity name.","commonSituations":"Typos or wrong case (the mapped name differs from the simple class name or @Entity(name=...) is set); entity lives in another persistence unit; class renamed during refactoring; using the FQN where only the unqualified name is registered.","solutions":["List the accepted names via em.getMetamodel().getEntities() and use the exact mapped name (mind case and quoting)","Check for @Entity(name=...) overrides and match that name","Ensure the entity is in the same persistence unit and picked up by scanning","For treat/type targets, verify the subclass is a mapped entity, not just a Java class"],"exampleFix":"// before\nselect treat(o as SpecialOrder) from Order o  // SpecialOrder not mapped\n\n// after\nselect treat(o as SpecialOrder) from Order o  // after adding @Entity to SpecialOrder and refreshing the SessionFactory","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// before building the query\nif (!isMappedEntityName(emf, entityName)) throw new IllegalArgumentException(\"Unknown entity name: \" + entityName);","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    // e.getEntityName() carries the unresolved name\n    throw new IllegalArgumentException(\"Entity not found in this persistence unit: \" + e.getEntityName(), e);\n}","preventionTips":["Validate entity names against em.getMetamodel().getEntities() when they come from user input or config","Log the accepted entity names at startup for quick diffing","Watch @Entity(name=...) overrides and case sensitivity"],"tags":["hql","entity-resolution","hibernate","metamodel"],"backgroundTag":"unknown-entity-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}