{"record":{"id":"25fc6168f48155c8","repo":"hibernate/hibernate-orm","slug":"property-element-not-found-on-collection","errorCode":null,"errorMessage":"property [\" + element + \"] not found on collection [\" + collection.getRole() + \"]","messagePattern":"property \\[\" \\+ element \\+ \"\\] not found on collection \\[\" \\+ collection\\.getRole\\(\\) \\+ \"\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java","lineNumber":590,"sourceCode":"\t\t\t\t\t\t}\n\t\t\t\t\t\telse if ( value instanceof OneToMany oneToMany ) {\n\t\t\t\t\t\t\tvalue = oneToMany.getAssociatedClass().getProperty( element ).getValue();\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse if ( value instanceof Collection collection ) {\n\t\t\t\t\t\t\tswitch ( element ) {\n\t\t\t\t\t\t\t\tcase \"key\":\n\t\t\t\t\t\t\t\t\tvalue = collection.getKey();\n\t\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\t\tcase \"element\":\n\t\t\t\t\t\t\t\t\tvalue = collection.getElement();\n\t\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\t\tcase \"index\":\n\t\t\t\t\t\t\t\t\tif ( collection instanceof IndexedCollection indexedCollection ) {\n\t\t\t\t\t\t\t\t\t\tvalue = indexedCollection.getIndex();\n\t\t\t\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\t\t\tthrow new MappingException( \"property [\" + element + \"] not found on collection [\" + collection.getRole() + \"]\" );\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse {\n\t\t\t\t\t\t\tthrow new AssertionFailure( \"Unexpected value\" );\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\treturn value;\n\t\t\t\t}\n\t\t\t\tcatch (MappingException e) {\n\t\t\t\t\tthrow new MappingException( \"property [\" + propertyPath + \"] not found on entity [\" + entityBinding.getEntityName() + \"]\" );\n\t\t\t\t}\n\t\t\t}\n\t\t\telse if ( parent instanceof CollectionResultDescriptor descriptor ) {\n\t\t\t\tfinal Collection collectionBinding =\n\t\t\t\t\t\tcollector.getCollectionBinding( descriptor.collectionPath.getFullPath() );\n\t\t\t\treturn collectionBinding.getElement();\n\t\t\t}\n\t\t\telse if ( parent instanceof JoinDescriptor joinDescriptor ) {","sourceCodeStart":572,"sourceCodeEnd":608,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java#L572-L608","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"<!-- before: 'stock' is not key/element/index -->\n<return-join alias=\"i\" property=\"o.items\">\n    <return-property name=\"element.stock\" column=\"STOCK\"/>\n</return-join>\n\n<!-- for a Map collection needing the key side -->\n<return-join alias=\"i\" property=\"o.items\">\n    <return-property name=\"key.localeCode\" column=\"LOCALE\"/>\n    <return-property name=\"element.name\" column=\"NAME\"/>\n</return-join>","handlingStrategy":"validation","validationCode":"// validate collection return-property paths against the collection binding before boot:\nString[] parts = propertyPath.split( \"\\\\.\" );\nif ( parts.length > 0 && isCollectionProperty( ownerProperty ) ) {\n    String first = parts[ parts.length - (parts.length - indexOfCollectionSegment( parts ) )]; // first segment after collection name\n    boolean indexed = collectionBinding instanceof IndexedCollection;\n    if ( !List.of( \"key\", \"element\" ).contains( first ) && !( \"index\".equals( first ) && indexed ) ) {\n        throw new IllegalStateException( \"Use key/element/index after a collection name, got: \" + propertyPath );\n    }\n}","typeGuard":null,"tryCatchPattern":"catch ( MappingException e ) {\n    if ( e.getMessage().contains( \"not found on entity\" ) && pathCrossesCollection ) {\n        // rewrite the path inserting key/element/index after the collection name\n    }\n}","preventionTips":["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."],"tags":["hibernate","hbm-xml","native-query","collections","property-path"],"backgroundTag":"collection-property-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}