hibernate/hibernate-orm · error · AnnotationException

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

Error message

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

What it means

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

Source

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

			AttributeNodeImplementor<?, ?, ?> attributeNode,
			boolean isKeySubGraph, Class<?> subgraphType) {
		if ( void.class.equals( subgraphType ) ) { // unspecified
			return attributeNode.addValueSubgraph();
		}
		else {
			return isKeySubGraph
					? makeAttributeNodeKeySubgraph( attributeNode, subgraphType )
					: makeAttributeNodeValueSubgraph( attributeNode, subgraphType );
		}
	}

	private static <T, E, K> SubGraphImplementor<?> makeAttributeNodeValueSubgraph(
			AttributeNodeImplementor<T, E, K> attributeNode, Class<?> subgraphType) {
		final var attributeValueType =
				attributeNode.getAttributeDescriptor()
						.getValueGraphType().getJavaType();
		if ( !attributeValueType.isAssignableFrom( subgraphType ) ) {
			throw new AnnotationException( "Named subgraph type '" + subgraphType.getName()
						+ "' is not a subtype of the value type '" + attributeValueType.getName() + "'" );
		}
		return attributeNode.addValueSubgraph().addTreatedSubgraph(
				subgraphType.asSubclass( attributeNode.getValueSubgraph().getClassType() ) );
	}

	private static <T, E, K> SubGraphImplementor<?> makeAttributeNodeKeySubgraph(
			AttributeNodeImplementor<T, E, K> attributeNode, Class<?> subgraphType) {
		final var attributeKeyType =
				attributeNode.getAttributeDescriptor()
						.getKeyGraphType().getJavaType();
		if ( !attributeKeyType.isAssignableFrom( subgraphType ) ) {
			throw new AnnotationException( "Named subgraph type '" + subgraphType.getName()
						+ "' is not a subtype of the key type '" + attributeKeyType.getName() + "'" );
		}
		return attributeNode.addKeySubgraph().addTreatedSubgraph(
				subgraphType.asSubclass( attributeNode.getKeySubgraph().getClassType() ) );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Make the named subgraph type a subtype of the map/collection value 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/b9e0c128686e37c7. Report an issue: GitHub.