hibernate/hibernate-orm · error · MappingException

property [" + element + "] not found on collection [" + coll

Error message

property [" + element + "] not found on collection [" + collection.getRole() + "]

What it means

While resolving a return-property path against a collection binding, getValue() accepts only 'key', 'element', or 'index' as the part that selects which collection side to descend into; 'index' additionally requires an IndexedCollection (list/map). Any other part falls through the switch default and throws this MappingException. Note the enclosing catch re-wraps it as 'property [path] not found on entity', so this exact message is usually masked (see error 748).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java:590

						}
						else if ( value instanceof OneToMany oneToMany ) {
							value = oneToMany.getAssociatedClass().getProperty( element ).getValue();
						}
						else if ( value instanceof Collection collection ) {
							switch ( element ) {
								case "key":
									value = collection.getKey();
									break;
								case "element":
									value = collection.getElement();
									break;
								case "index":
									if ( collection instanceof IndexedCollection indexedCollection ) {
										value = indexedCollection.getIndex();
										break;
									}
								default:
									throw new MappingException( "property [" + element + "] not found on collection [" + collection.getRole() + "]" );
							}
						}
						else {
							throw new AssertionFailure( "Unexpected value" );
						}
					}
					return value;
				}
				catch (MappingException e) {
					throw new MappingException( "property [" + propertyPath + "] not found on entity [" + entityBinding.getEntityName() + "]" );
				}
			}
			else if ( parent instanceof CollectionResultDescriptor descriptor ) {
				final Collection collectionBinding =
						collector.getCollectionBinding( descriptor.collectionPath.getFullPath() );
				return collectionBinding.getElement();
			}
			else if ( parent instanceof JoinDescriptor joinDescriptor ) {

View on GitHub (pinned to fad1729dce)

Solutions

Prefix the path with the collection part: 'items.element.stock', 'items.key.id', or 'items.index.name'.
Use 'key'/'element' for the id/value side of a map, 'element' for set/bag contents, and 'index' only for lists and maps.
If you need an indexed-style access on a set, remap the collection as a list/map or drop the index part.

Example fix

<!-- before: 'stock' is not key/element/index -->
<return-join alias="i" property="o.items">
    <return-property name="element.stock" column="STOCK"/>
</return-join>

<!-- for a Map collection needing the key side -->
<return-join alias="i" property="o.items">
    <return-property name="key.localeCode" column="LOCALE"/>
    <return-property name="element.name" column="NAME"/>
</return-join>

Defensive patterns

Strategy: validation

Validate before calling

// validate collection return-property paths against the collection binding before boot:
String[] parts = propertyPath.split( "\\." );
if ( parts.length > 0 && isCollectionProperty( ownerProperty ) ) {
    String first = parts[ parts.length - (parts.length - indexOfCollectionSegment( parts ) )]; // first segment after collection name
    boolean indexed = collectionBinding instanceof IndexedCollection;
    if ( !List.of( "key", "element" ).contains( first ) && !( "index".equals( first ) && indexed ) ) {
        throw new IllegalStateException( "Use key/element/index after a collection name, got: " + propertyPath );
    }
}

Try / catch

catch ( MappingException e ) {
    if ( e.getMessage().contains( "not found on entity" ) && pathCrossesCollection ) {
        // rewrite the path inserting key/element/index after the collection name
    }
}

Prevention

Memorize the collection-part vocabulary: key, element, index; index only for lists and maps.
Cover each native query involving collections with a smoke test that executes the query.

When it happens

Trigger: A return-property path on a collection join like 'items.stock' where the first part is neither key/element/index; using 'index' against a Set or bag (not an IndexedCollection); assuming child property names can follow the collection name directly.

Common situations: Porting HQL-style paths ('items.stock') into native-query return-property syntax which requires the explicit collection-part segment; joining a map/list collection with the index segment against a set.

Related errors

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