{"record":{"id":"2204b427821c5e9c","repo":"hibernate/hibernate-orm","slug":"cannot-resolve-entity-name","errorCode":null,"errorMessage":"Cannot resolve entity name : {}","messagePattern":"Cannot resolve entity name : (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/JpaMetamodelImpl.java","lineNumber":526,"sourceCode":"\t\tfor ( var definition : namedEntityGraphs ) {\n\t\t\tCORE_LOGGER.tracef( \"Applying named entity graph [name=%s, source=%s]\",\n\t\t\t\t\tdefinition.name(), definition.source() );\n\n\t\t\tfinal var graph = definition.graphCreator().createEntityGraph(\n\t\t\t\t\tentityClass -> {\n\t\t\t\t\t\tif ( managedTypeByClass.get( entityClass ) instanceof EntityDomainType<?> match ) {\n\t\t\t\t\t\t\treturn match;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tthrow new IllegalArgumentException( \"Cannot resolve entity class : \" + entityClass.getName() );\n\t\t\t\t\t},\n\t\t\t\t\tjpaEntityName -> {\n\t\t\t\t\t\tfor ( var entry : managedTypeByName.entrySet() ) {\n\t\t\t\t\t\t\tif ( entry.getValue() instanceof EntityDomainType<?> possibility\n\t\t\t\t\t\t\t\t\t&& jpaEntityName.equals( possibility.getName() ) ) {\n\t\t\t\t\t\t\t\treturn possibility;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\tthrow new IllegalArgumentException( \"Cannot resolve entity name : \" + jpaEntityName );\n\t\t\t\t\t},\n\t\t\t\t\tserviceRegistry\n\t\t\t);\n\t\t\tentityGraphMap.put( definition.name(), graph );\n\t\t}\n\t}\n\n\n\tprivate Class<?> resolveRequestedClass(String entityName) {\n\t\ttry {\n\t\t\treturn classLoaderService.classForName( entityName );\n\t\t}\n\t\tcatch (ClassLoadingException e) {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t@Nonnull","sourceCodeStart":508,"sourceCodeEnd":544,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/JpaMetamodelImpl.java#L508-L544","documentation":"Thrown from the same JpaMetamodelImpl.applyNamedEntityGraphs bootstrap path, but by the name-based resolver lambda. Named entity graph definitions that reference entities by JPA entity name (XML entity graphs in orm.xml, or text/parsed graph definitions) are matched against every EntityDomainType's getName(); no match aborts startup with 'Cannot resolve entity name'.","triggerScenarios":"An orm.xml <entity-graph> or text graph definition naming an entity that is not mapped (typo, wrong case); renaming an entity via @Entity(name=\"X\") while the graph still uses the old/unqualified class name; a graph definition referencing an entity registered in a different persistence unit.","commonSituations":"Default entity name is the unqualified class name — code that assumes the fully-qualified name fails; @Entity(name=...) rename refactors miss graph definitions in XML; merging modules moves an entity to a new PU but leaves its graph behind.","solutions":["Use the exact registered JPA entity name: default is the unqualified class name, otherwise the @Entity(name=...) value","Fix typos/casing in the entity name inside the orm.xml entity-graph or graph definition","Move the entity-graph definition into the same persistence unit as the entity it references","Prefer annotation-based @NamedEntityGraph with type references over name-based references to avoid name drift"],"exampleFix":"// before (orm.xml)\n<entity-graph name=\"order-graph\">\n  <named-attribute-node name=\"items\"/>\n</entity-graph>\n<!-- graph assumed for entity 'ORD' but defined on class with @Entity(name = \"ORD\") and referenced as 'Order' elsewhere -->\n\n// after\n@NamedQuery-less fix: reference 'ORD' wherever the graph names the entity, or rename the entity:\n@Entity(name = \"Order\") public class Order { ... }","handlingStrategy":"validation","validationCode":"// Compute the set of JPA entity names exactly as Hibernate registers them\nSet<String> entityNames = scannedEntityClasses.stream()\n    .map(c -> {\n      jakarta.persistence.Entity e = c.getAnnotation(jakarta.persistence.Entity.class);\n      return (e != null && !e.name().isEmpty()) ? e.name() : c.getSimpleName();\n    })\n    .collect(Collectors.toSet());\n// Assert every entity-name reference in your graph definitions (orm.xml / parsed graphs) is contained\nfor (String referenced : graphReferencedNames) {\n  if (!entityNames.contains(referenced)) {\n    throw new IllegalStateException(\"Graph references unknown entity name '\" + referenced + \"'; known: \" + entityNames);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  emf = Persistence.createEntityManagerFactory(puName);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Cannot resolve entity name\")) {\n    throw new IllegalStateException(\"Entity graph references an unregistered entity name: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Remember entity names default to the UNQUALIFIED class name — never use fully-qualified names in graphs","When renaming via @Entity(name=...), update every XML/text graph definition in the same commit","Prefer annotation-based graphs with type references over name-based references where possible"],"tags":["hibernate","jpa","entity-graph","entity-name","bootstrap"],"backgroundTag":"entity-name-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}