{"record":{"id":"2f1a672c7fb71556","repo":"hibernate/hibernate-orm","slug":"the-root-parameter-of-the-namedentitygraph-anno","errorCode":null,"errorMessage":"The 'root' parameter of the @NamedEntityGraph annotation must reference the entity '${entity}', but '${provided}' was provided. Graph :${name}","messagePattern":"The 'root' parameter of the @NamedEntityGraph annotation must reference the entity '(.+?)', but '(.+?)' was provided\\. Graph :(.+?)","errorType":"exception","errorClass":"InvalidNamedEntityGraphParameterException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/NamedGraphCreatorParsed.java","lineNumber":147,"sourceCode":"\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\n\t\t\t//noinspection unchecked\n\t\t\treturn (EntityDomainType<T>) entityDomainClassResolver.resolveEntityClass( annotationRootAttribute );\n\t\t}\n\n\t\t//noinspection unchecked\n\t\treturn (EntityDomainType<T>) entityDomainClassResolver.resolveEntityClass( entityType );\n\t}\n\n}\n","sourceCodeStart":129,"sourceCodeEnd":164,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/NamedGraphCreatorParsed.java#L129-L164","documentation":"When a @NamedEntityGraph is placed on an entity class AND explicitly sets the 'root' parameter, Hibernate requires the two types to agree. The graph is being registered for the owning entity, but 'root' names a different class, which would bind the attribute paths against the wrong entity type, so bootstrap fails with InvalidNamedEntityGraphParameterException.","triggerScenarios":"@Entity class Order { ... } annotated with @NamedEntityGraph(name=\"g\", root = Customer.class) where Customer.class != the annotated entity class; typically a copy-paste of a graph from one entity to another without updating (or removing) the root parameter.","commonSituations":"Copying a working @NamedEntityGraph between entity classes and forgetting to clear or update 'root'; merging graph definitions during refactoring; XML-to-annotation migration where the root was copied from the original entity.","solutions":["Remove the 'root' parameter entirely — when the graph sits on the entity class, the owner is the implicit root.","Or set root = <the owning entity class> so it matches the class carrying the annotation.","Or move the graph to the entity that 'root' actually references."],"exampleFix":"// before\n@Entity\n@NamedEntityGraph(name = \"order.full\", root = Customer.class)\npublic class Order { ... }\n\n// after\n@Entity\n@NamedEntityGraph(name = \"order.full\")   // root defaults to Order\npublic class Order { ... }","handlingStrategy":"validation","validationCode":"// Assert root (when set) matches the entity carrying the graph\nfor (Class<?> entity : annotatedClasses) {\n    for (var g : entity.getAnnotationsByType(NamedEntityGraph.class)) {\n        if (!void.class.equals(g.root()) && !g.root().equals(entity)) {\n            throw new IllegalStateException(\"Graph '\" + g.name() + \"' on \" + entity.getName() + \" has mismatched root \" + g.root().getName());\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    Metadata metadata = metadataSources.buildMetadata();\n} catch (InvalidNamedEntityGraphParameterException e) {\n    throw new IllegalStateException(\"Entity graph root mismatch: \" + e.getMessage(), e);\n}","preventionTips":["Omit the root parameter when the graph lives on the entity class","When copy-pasting a graph between entities, delete or update 'root'"],"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"}