{"record":{"id":"9a5715a5bf2b020f","repo":"hibernate/hibernate-orm","slug":"the-root-parameter-of-the-namedentitygraph-shou","errorCode":null,"errorMessage":"The 'root' parameter of the @NamedEntityGraph should be passed. Graph : ${name}","messagePattern":"The 'root' parameter of the @NamedEntityGraph should be passed\\. Graph : (.+?)","errorType":"exception","errorClass":"InvalidNamedEntityGraphParameterException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/NamedGraphCreatorParsed.java","lineNumber":136,"sourceCode":"\t\telse {\n\t\t\tentityDomainType = resolveEntityDomainTypeFromAnnotation( entityDomainClassResolver );\n\t\t}\n\n\n\t\tfinal String graphName = this.name == null ? entityDomainType.getName() : this.name;\n\n\t\treturn GraphParsing.visit( graphName, entityDomainType, graphContext.attributeList(),\n\t\t\t\tentityName -> resolve( entityName, entityDomainNameResolver ) );\n\t}\n\n\n\tprivate <T> EntityDomainType<T> resolveEntityDomainTypeFromAnnotation(GraphParserEntityClassResolver entityDomainClassResolver) {\n\t\tfinal Class<?> annotationRootAttribute = annotation.root();\n\t\tfinal boolean isAnnotationRootAttributeVoid = void.class.equals( annotationRootAttribute );\n\n\t\tif ( entityType == null ) {\n\t\t\tif ( isAnnotationRootAttributeVoid ) {\n\t\t\t\tthrow new InvalidNamedEntityGraphParameterException(\n\t\t\t\t\t\t\"The 'root' parameter of the @NamedEntityGraph should be passed. Graph : \" + annotation.name()\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t//noinspection unchecked\n\t\t\treturn (EntityDomainType<T>) entityDomainClassResolver.resolveEntityClass( annotationRootAttribute );\n\t\t}\n\n\t\tif ( !isAnnotationRootAttributeVoid ) {\n\t\t\tif ( !annotationRootAttribute.equals( entityType ) ) {\n\t\t\t\tthrow new InvalidNamedEntityGraphParameterException(\n\t\t\t\t\t\t\"The 'root' parameter of the @NamedEntityGraph annotation must reference the entity '\"\n\t\t\t\t\t\t+ entityType.getName()\n\t\t\t\t\t\t+ \"', but '\" + annotationRootAttribute.getName() + \"' was provided.\"\n\t\t\t\t\t\t+ \" Graph :\" + annotation.name()\n\t\t\t\t);\n\t\t\t}\n","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/NamedGraphCreatorParsed.java#L118-L154","documentation":"Hibernate throws this while building metadata when a @NamedEntityGraph declaration carries no resolvable root entity type. The parser only needs the annotation's 'root' attribute when the graph is not attached to a known entity class (e.g. declared in XML, on a package, or processed without an owning entity); if 'root' is left at its default void.class in that situation, the graph cannot be bound to any entity and bootstrap fails with InvalidNamedEntityGraphParameterException.","triggerScenarios":"Declaring @NamedEntityGraph (or a <named-entity-graph> in orm.xml) without a 'root' element/attribute in a location where no entity type is supplied: orm.xml graphs not nested inside an <entity>, package-level declarations, or programmatic/annotation processing paths where entityType is null and annotation.root() == void.class.","commonSituations":"Migrating entity graphs from annotations to orm.xml (or vice versa) and forgetting the root; declaring shared graphs in package-info.java; splitting graph definitions out of the entity class during refactoring; upgrading Hibernate versions where previously-lenient parsing now enforces the root.","solutions":["Add root = YourEntity.class to the @NamedEntityGraph (or the corresponding root element in orm.xml).","Move the @NamedEntityGraph annotation directly onto the entity class it applies to, where the owner supplies the root implicitly.","In orm.xml, nest the <named-entity-graph> inside the <entity> element instead of declaring it at the mapping-file root."],"exampleFix":"// before (orm.xml or package-level declaration, no entity context)\n@NamedEntityGraph(name = \"order.withLines\")\n\n// after\n@NamedEntityGraph(name = \"order.withLines\", root = Order.class)\n// or: put the annotation on the Order entity class itself","handlingStrategy":"validation","validationCode":"// Fail fast before SessionFactory build: every graph without an owning entity needs a root\nfor (var pkg : Package.getPackages()) {\n    var graphs = pkg.isAnnotationPresent(NamedEntityGraphs.class)\n            ? pkg.getAnnotation(NamedEntityGraphs.class).value()\n            : new NamedEntityGraph[0];\n    for (var g : graphs) {\n        if (void.class.equals(g.root())) {\n            throw new IllegalStateException(\"@NamedEntityGraph '\" + g.name() + \"' outside an entity must set root=\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    Metadata metadata = metadataSources.buildMetadata();\n} catch (InvalidNamedEntityGraphParameterException e) {\n    throw new IllegalStateException(\"Entity graph misconfigured: \" + e.getMessage(), e);\n}","preventionTips":["Always set root explicitly when declaring graphs outside the entity class","Keep @NamedEntityGraph on the entity it targets so the root is implicit","In orm.xml, nest named-entity-graph inside its <entity>"],"tags":["hibernate","jpa","entity-graph","named-entity-graph","bootstrap","annotation-config"],"backgroundTag":"named-entity-graph-misconfigured","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}