hibernate/hibernate-orm · error · AnnotationException

Named subgraph type '${type}' is not a subtype of the graph

Error message

Named subgraph type '${type}' is not a subtype of the graph type '${graphType}'

What it means

Error "Named subgraph type '${type}' is not a subtype of the graph type '${graphType}'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/NamedGraphCreatorJpa.java:85

	public RootGraphImplementor<?> createEntityGraph(
			GraphParserEntityClassResolver entityDomainClassResolver,
			GraphParserEntityNameResolver entityDomainNameResolver,
			ServiceRegistry serviceRegistry) {
		return createGraph( (EntityDomainType<?>)
				entityDomainNameResolver.resolveEntityName( jpaEntityName ) );
	}

	private <T> @Nonnull RootGraphImplementor<T> createGraph(EntityDomainType<T> rootEntityType) {
		validateFetchContributions();
		final var entityGraph =
				createRootGraph( name, rootEntityType, annotation.includeAllAttributes() );
		final var subclassSubgraphs = annotation.subclassSubgraphs();
		if ( subclassSubgraphs != null ) {
			for ( var subclassSubgraph : subclassSubgraphs ) {
				final var subgraphType = subclassSubgraph.type();
				final var graphJavaType = entityGraph.getGraphedType().getJavaType();
				if ( !graphJavaType.isAssignableFrom( subgraphType ) ) {
					throw new AnnotationException( "Named subgraph type '" + subgraphType.getName()
								+ "' is not a subtype of the graph type '" + graphJavaType.getName() + "'" );
				}
				applyNamedAttributeNodes( subclassSubgraph.attributeNodes(), annotation,
						entityGraph.addTreatedSubgraph( subgraphType.asSubclass( graphJavaType ) ), "", fetchContributions );
			}
		}
		if ( annotation.attributeNodes() != null ) {
			applyNamedAttributeNodes( annotation.attributeNodes(), annotation, entityGraph, null, fetchContributions );
		}
		else {
			applyFetchContributions( entityGraph, null, fetchContributions, name );
		}
		return entityGraph;
	}

	private static <T> RootGraphImplementor<T> createRootGraph(
			String name,
			EntityDomainType<T> rootEntityType,

View on GitHub (pinned to fad1729dce)

Solutions

1. Make the named subgraph type a subtype of the entity graph root type.

When it happens

Trigger: A named entity graph / fetch declaration references unknown or incompatible types, attributes, or subgraphs.

Common situations: @Fetch pointing at an unknown graph, subgraph types that are not subtypes of the attribute type, or conflicting fetch options for the same attribute.

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