hibernate/hibernate-orm · error · InvalidNamedEntityGraphParameterException

The 'root' parameter of the @NamedEntityGraph annotation mus

Error message

The 'root' parameter of the @NamedEntityGraph annotation must reference the entity '${entity}', but '${provided}' was provided. Graph :${name}

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/NamedGraphCreatorParsed.java:147

	private <T> EntityDomainType<T> resolveEntityDomainTypeFromAnnotation(GraphParserEntityClassResolver entityDomainClassResolver) {
		final Class<?> annotationRootAttribute = annotation.root();
		final boolean isAnnotationRootAttributeVoid = void.class.equals( annotationRootAttribute );

		if ( entityType == null ) {
			if ( isAnnotationRootAttributeVoid ) {
				throw new InvalidNamedEntityGraphParameterException(
						"The 'root' parameter of the @NamedEntityGraph should be passed. Graph : " + annotation.name()
				);
			}

			//noinspection unchecked
			return (EntityDomainType<T>) entityDomainClassResolver.resolveEntityClass( annotationRootAttribute );
		}

		if ( !isAnnotationRootAttributeVoid ) {
			if ( !annotationRootAttribute.equals( entityType ) ) {
				throw new InvalidNamedEntityGraphParameterException(
						"The 'root' parameter of the @NamedEntityGraph annotation must reference the entity '"
						+ entityType.getName()
						+ "', but '" + annotationRootAttribute.getName() + "' was provided."
						+ " Graph :" + annotation.name()
				);
			}

			//noinspection unchecked
			return (EntityDomainType<T>) entityDomainClassResolver.resolveEntityClass( annotationRootAttribute );
		}

		//noinspection unchecked
		return (EntityDomainType<T>) entityDomainClassResolver.resolveEntityClass( entityType );
	}

}

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the 'root' parameter entirely — when the graph sits on the entity class, the owner is the implicit root.
2. Or set root = <the owning entity class> so it matches the class carrying the annotation.
3. Or move the graph to the entity that 'root' actually references.

Example fix

// before
@Entity
@NamedEntityGraph(name = "order.full", root = Customer.class)
public class Order { ... }

// after
@Entity
@NamedEntityGraph(name = "order.full")   // root defaults to Order
public class Order { ... }

// Assert root (when set) matches the entity carrying the graph
for (Class<?> entity : annotatedClasses) {
    for (var g : entity.getAnnotationsByType(NamedEntityGraph.class)) {
        if (!void.class.equals(g.root()) && !g.root().equals(entity)) {
            throw new IllegalStateException("Graph '" + g.name() + "' on " + entity.getName() + " has mismatched root " + g.root().getName());
        }
    }
}

try {
    Metadata metadata = metadataSources.buildMetadata();
} catch (InvalidNamedEntityGraphParameterException e) {
    throw new IllegalStateException("Entity graph root mismatch: " + e.getMessage(), e);
}

When it happens

Trigger: @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.

Common situations: 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.

Related errors

• The 'root' parameter of the @NamedEntityGraph should be pass
• Cannot resolve entity class : {}
• Cannot resolve entity name : {}
• AttributeConverter class [%s] registered multiple times
• Duplicate named entity graph '%s'

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/2f1a672c7fb71556. Report an issue: GitHub.