hibernate/hibernate-orm · error · CannotContainSubGraphException

Attribute '{}' is not a to-one association

Error message

Attribute '{}' is not a to-one association

What it means

Before creating a singular subgraph, checkToOne() verifies the attribute is a to-one association or an embedding (MANY_TO_ONE, ONE_TO_ONE or EMBEDDED). A subgraph needs a managed type to descend into; a basic value or a collection cannot provide one, so CannotContainSubGraphException is thrown.

Source

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

		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 ) {
			throw new CannotContainSubGraphException( "Attribute '" + attribute.getName() + "' is not a to-many association" );
		}
	}

	protected <T> ManagedDomainType<T> asManagedType(DomainType<T> domainType) {
		if ( domainType instanceof ManagedDomainType<T> managedDomainType ) {
			return managedDomainType;
		}
		else {
			throw new CannotContainSubGraphException( "Attribute '" + description()
					+ "' is of type '" + domainType.getTypeName()
					+ "' which is not a managed type" );

View on GitHub (pinned to fad1729dce)

Solutions

1. Keep addSubgraph()/addSingularSubgraph() for to-one (@ManyToOne/@OneToOne) and @Embedded attributes only
2. For collection attributes use addElementSubgraph() (or addKeySubgraph() for map keys)
3. For basic attributes there is no subgraph — control their loading by adding/removing the attribute node itself
4. Update legacy subgraph() calls on collections to addElementSubgraph()

Example fix

// before — singular node for a basic attribute cannot carry a subgraph
graph.addAttributeNode("version")   // basic int attribute
     .addSingularSubgraph();         // → CannotContainSubGraphException

// after — subgraphs belong to to-one/embedded attributes
graph.addAttributeNode("supplier")  // @ManyToOne
     .addSingularSubgraph()
     .addAttributeNode("address");

if (acceptsSingularSubgraph(attr)) {
    node.addSingularSubgraph().addAttributeNode("address");
}

static boolean acceptsSingularSubgraph(Attribute<?, ?> attr) {
    return switch (attr.getPersistentAttributeType()) {
        case MANY_TO_ONE, ONE_TO_ONE, EMBEDDED -> true;
        default -> false;
    };
}

When it happens

Trigger: addSubgraph()/addSingularSubgraph() on a node whose attribute is a basic type (String, enum, Instant, int) — e.g. graph.addAttributeNode("version").addSingularSubgraph(); also singular non-association attributes like a basic-type SingularAttribute.

Common situations: Graph-building helpers that call addSubgraph for every node; porting pre-Hibernate-6 code where subgraph() was accepted on collection attributes (now routed to addElementSubgraph); copying JPA 2-era examples onto Hibernate 6/7.

Related errors

• Not a singular attribute node
• Attribute '{}' is of type '{}' which is not a managed type
• Duplicate named entity graph '%s'
• The 'root' parameter of the @NamedEntityGraph should be pass
• The 'root' parameter of the @NamedEntityGraph annotation mus

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