hibernate/hibernate-orm · error · UnsupportedOperationException

Not a collection-valued attribute node

Error message

Not a collection-valued attribute node

What it means

addElementSubgraph() is implemented only on collection nodes (PluralAttributeNodeImpl and MapAttributeNodeImpl). Calling it on a node for a singular attribute — where there are no collection elements — falls through to the base-class implementation and throws UnsupportedOperationException.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/graph/internal/AttributeNodeImpl.java:207

		verifyMutability();
		setFetchType( FetchType.EAGER );
		// this one is intentionally lenient and disfavored
		if ( valueSubgraph == null ) {
			valueSubgraph = new SubGraphImpl<>( asManagedType( valueGraphType ), true );
		}
		return valueSubgraph;
	}

	@Override
	@Nonnull
	public SubGraphImplementor<J> addSingularSubgraph() {
		throw new UnsupportedOperationException("Not a singular attribute node");
	}

	@Override
	@Nonnull
	public SubGraphImplementor<E> addElementSubgraph() {
		throw new UnsupportedOperationException( "Not a collection-valued attribute node" );
	}

	@Override
	@Nonnull
	public SubGraphImplementor<K> addKeySubgraph() {
		throw new UnsupportedOperationException( "Not a Map-valued attribute node" );
	}

	protected void checkToOne() {
		final Attribute.PersistentAttributeType attributeType = attribute.getPersistentAttributeType();
		if ( attributeType != MANY_TO_ONE && attributeType != ONE_TO_ONE && attributeType != EMBEDDED ) {
			throw new CannotContainSubGraphException( "Attribute '" + attribute.getName() + "' is not a to-one association" );
		}
	}

	protected void checkToMany() {
		final Attribute.PersistentAttributeType attributeType = attribute.getPersistentAttributeType();
		if ( attributeType != MANY_TO_MANY && attributeType != ONE_TO_MANY ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Use addSingularSubgraph() (or addSubgraph()) for to-one/embedded attributes
2. Reserve addElementSubgraph() for collection and Map element subgraphs
3. Branch on attr instanceof PluralAttribute in generic graph builders

Example fix

// before
graph.addAttributeNode("customer").addElementSubgraph(); // customer is @ManyToOne → throws

// after
graph.addAttributeNode("customer")
     .addSingularSubgraph()
     .addAttributeNode("address");

if (isCollection(node.getAttribute())) {
    node.addElementSubgraph().addAttributeNode("name");
}
else {
    node.addSingularSubgraph().addAttributeNode("name");
}

static boolean isCollection(Attribute<?, ?> attr) {
    return attr instanceof jakarta.persistence.metamodel.PluralAttribute<?, ?, ?>;
}

When it happens

Trigger: node.addElementSubgraph() on an attribute node for a @ManyToOne, @OneToOne, @Embedded or basic attribute; usually generic code that always uses the element variant regardless of attribute kind.

Common situations: Adopting the JPA 3.2 AttributeNode API uniformly across nodes; switching an association from to-many back to to-one; copy-paste between nodes of different kinds.

Related errors

• Not a singular attribute node
• Not a Map-valued attribute node
• Attribute '{}' is not a to-many association
• No node for attribute: {}
• Duplicate named entity graph '%s'

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