hibernate/hibernate-orm · error · AnnotationException

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

Error message

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

What it means

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

Source

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

			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 key 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/da272cd30653cf35. Report an issue: GitHub.