{"record":{"id":"b2688d02f62d5433","repo":"hibernate/hibernate-orm","slug":"cannot-resolve-entity-class","errorCode":null,"errorMessage":"Cannot resolve entity class : {}","messagePattern":"Cannot resolve entity class : (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/JpaMetamodelImpl.java","lineNumber":517,"sourceCode":"\t\t\t\t\tfinal var info = new ImportInfo( name, loadedClass );\n\t\t\t\t\tnameToImportMap.put( name, info );\n\t\t\t\t\treturn info;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate void applyNamedEntityGraphs(Collection<NamedEntityGraphDefinition> namedEntityGraphs) {\n\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) {","sourceCodeStart":499,"sourceCodeEnd":535,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/JpaMetamodelImpl.java#L499-L535","documentation":"Hibernate throws this IllegalArgumentException while applying @NamedEntityGraph definitions during SessionFactory/EntityManagerFactory bootstrap. JpaMetamodelImpl.applyNamedEntityGraphs resolves every entity class referenced by the graph (root and subgraphs) against managedTypeByClass; a class that is not a registered managed type aborts startup. The graphCreator lambda has no fallback: any non-entity class in a @NamedSubgraph(type=...) triggers the throw.","triggerScenarios":"An @NamedEntityGraph on an entity declares @NamedSubgraph(type = X.class) where X is not an @Entity in the same persistence unit (a DTO, @MappedSuperclass, embeddable, or entity from another PU); an XML <entity-graph> or orm.xml graph referencing an unmanaged class; a graph definition copied from another mapping where the class is no longer mapped.","commonSituations":"Subgraph type accidentally points at the embeddable instead of the embedding entity; refactor renamed or moved the target class but the graph still references the old one; entity classes listed explicitly in persistence.xml and the graph target was never added; splitting one PU into two leaves the graph in a PU that no longer maps the referenced class.","solutions":["Make every class used in @NamedSubgraph(type=...) a real @Entity in the same persistence unit","If the subgraph targets an @Embedded attribute, restructure the graph so the @NamedSubgraph is typed with the embedding entity and attribute nodes walk into the embeddable","Verify the class is actually picked up by the persistence unit (persistence.xml <class> entries, package auto-detection, or the Spring-equivalent entity scan)","Delete stale @NamedEntityGraph/@NamedSubgraph definitions that reference classes no longer mapped"],"exampleFix":"// before\n@NamedEntityGraph(\n  name = \"order-graph\",\n  attributeNodes = @NamedAttributeNode(value = \"items\", subgraph = \"items-subgraph\")),\n  subgraphs = @NamedSubgraph(\n    name = \"items-subgraph\",\n    type = OrderLineId.class /* not an @Entity */) // throws 'Cannot resolve entity class'\n\n// after\n@NamedEntityGraph(\n  name = \"order-graph\",\n  attributeNodes = @NamedAttributeNode(value = \"items\", subgraph = \"items-subgraph\")),\n  subgraphs = @NamedSubgraph(\n    name = \"items-subgraph\",\n    type = OrderLine.class /* @Entity */)  // or drop the subgraph and rely on default fetch","handlingStrategy":"validation","validationCode":"// Before building the EntityManagerFactory, verify every @NamedSubgraph type is a mapped @Entity\nfor (Class<?> entity : scannedEntityClasses) {\n  for (jakarta.persistence.NamedEntityGraph graph : entity.getAnnotationsByType(jakarta.persistence.NamedEntityGraph.class)) {\n    for (jakarta.persistence.NamedSubgraph sub : graph.subgraphs()) {\n      if (!sub.type().isAnnotationPresent(jakarta.persistence.Entity.class)) {\n        throw new IllegalStateException(\n          \"Graph on \" + entity.getName() + \" references non-entity subgraph type \" + sub.type().getName());\n      }\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  emf = Persistence.createEntityManagerFactory(puName);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Cannot resolve entity class\")) {\n    throw new IllegalStateException(\"Bad @NamedEntityGraph subgraph type (not an @Entity): \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Keep @NamedEntityGraph annotations directly on the entity classes they describe, with subgraph types from the same persistence unit","Add a startup self-test (build the EMF in CI) so graph-to-entity mismatches fail the build, not production","After moving/renaming entities, grep all @NamedSubgraph(type=...) references and update them"],"tags":["hibernate","jpa","entity-graph","bootstrap","metamodel"],"backgroundTag":"entity-class-not-managed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}