{"record":{"id":"833e35490a12e82a","repo":"hibernate/hibernate-orm","slug":"error-transforming-element-collection","errorCode":null,"errorMessage":"Error transforming element-collection : ","messagePattern":"Error transforming element-collection : ","errorType":"exception","errorClass":"TransformationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/hbm/transform/HbmXmlTransformer.java","lineNumber":2210,"sourceCode":"\t\t\t\t}\n\t\t\t}\n\t\t\telse if ( hbmAttributeMapping instanceof JaxbHbmAnyAssociationType any ) {\n\t\t\t\ttry {\n\t\t\t\t\tfinal var propertyInfo = managedTypeInfo.propertyInfoMap().get( any.getName() );\n\t\t\t\t\tattributes.getAnyMappingAttributes().add( transformAnyAttribute( any, propertyInfo ) );\n\t\t\t\t}\n\t\t\t\tcatch (Exception e) {\n\t\t\t\t\tthrow new TransformationException( \"Error transforming <any/> : \" + any.getName(), e, origin() );\n\t\t\t\t}\n\t\t\t}\n\t\t\telse if ( hbmAttributeMapping instanceof PluralAttributeInfo hbmCollection ) {\n\t\t\t\tfinal var propertyInfo = managedTypeInfo.propertyInfoMap().get( hbmCollection.getName() );\n\t\t\t\tif ( hbmCollection.getElement() != null || hbmCollection.getCompositeElement() != null ) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tattributes.getElementCollectionAttributes().add( transformElementCollection( roleBase, hbmCollection, propertyInfo ) );\n\t\t\t\t\t}\n\t\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t\tthrow new TransformationException( \"Error transforming element-collection : \" + hbmCollection.getName(), e, origin() );\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\telse if ( hbmCollection.getOneToMany() != null ) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tattributes.getOneToManyAttributes().add( transformOneToMany( hbmCollection, propertyInfo ) );\n\t\t\t\t\t}\n\t\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t\tthrow new TransformationException( \"Error transforming one-to-many : \" + hbmCollection.getName(), e, origin() );\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\telse if ( hbmCollection.getManyToMany() != null ) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tif ( hbmCollection.getManyToMany().isUnique() ) {\n\t\t\t\t\t\t\tattributes.getOneToManyAttributes().add( transformManyToManyToOneToMany( hbmCollection, propertyInfo ) );\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse {\n\t\t\t\t\t\t\tattributes.getManyToManyAttributes().add( transformManyToMany( hbmCollection, propertyInfo ) );\n\t\t\t\t\t\t}","sourceCodeStart":2192,"sourceCodeEnd":2228,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/hbm/transform/HbmXmlTransformer.java#L2192-L2228","documentation":"Thrown by Hibernate 6's legacy-hbm-to-mapping.xml transformer (HbmXmlTransformer) when transforming a collection mapped with <element/> or <composite-element/> (an element-collection) fails. The TransformationException wraps the real cause and attaches the Origin (source file/position) of the offending mapping. The outer message only names the collection property; the actionable detail is always in getCause().","triggerScenarios":"Running hbm.xml->mapping.xml transformation on a <set>/<list>/<bag>/<map>/<array> whose body contains <element> or <composite-element>, where transformElementCollection throws: unresolvable type attribute, a composite-element class missing from the classpath, a bad column/formula definition, or a mismatch with the boot model's property info.","commonSituations":"Migrating a Hibernate 3/4/5 codebase that mixes hbm.xml with modern bootstrapping; custom UserType/CompositeUserType element types not registered where the transformer runs; typos in the 'type' or 'class' attributes of element/composite-element.","solutions":["Inspect exception.getCause() first - it carries the real reason (unknown type, ClassNotFound, invalid column); the outer message only identifies the collection name","Verify every <element type=\"...\"> resolves: custom types must be registered (TypeContributor/service registry) on the classpath used for transformation","Check each <composite-element class=\"...\"> names a loadable class","Fix the offending collection in the hbm.xml and re-run the transformation","If the construct is valid hbm but the transformer cannot handle it, leave that mapping as native hbm.xml - Hibernate 6 still binds hbm.xml directly without transformation"],"exampleFix":"<!-- before -->\n<set name=\"labels\" table=\"labels\">\n    <element type=\"com.acme.LabelTypo\" column=\"label\"/>\n</set>\n\n<!-- after -->\n<set name=\"labels\" table=\"labels\">\n    <element type=\"string\" column=\"label\"/>\n</set>","handlingStrategy":"try-catch","validationCode":"// fail fast before transforming: composite-element classes must be loadable\nvar doc = javax.xml.parsers.DocumentBuilderFactory.newInstance()\n        .newDocumentBuilder().parse(hbmFile);\nvar nodes = doc.getElementsByTagName(\"composite-element\");\nfor (int i = 0; i < nodes.getLength(); i++) {\n    String cls = ((org.w3c.dom.Element) nodes.item(i)).getAttribute(\"class\");\n    Class.forName(cls); // throws ClassNotFoundException with the real name\n}","typeGuard":null,"tryCatchPattern":"try {\n    transformer.transform(hbmSource);\n} catch (TransformationException e) {\n    // message names the collection; cause holds the real failure\n    log.error(\"element-collection transform failed: {} cause={}\", e.getMessage(), e.getCause().getMessage());\n    throw e;\n}","preventionTips":["Always log the wrapped cause - the outer message only identifies the property","Run the transformer over all hbm files together in CI so referenced types/classes resolve","Keep custom types and composite classes on the transformation classpath"],"tags":["hibernate","hbm-xml","element-collection","mapping-transformation","orm"],"backgroundTag":"orm-mapping-transformation-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}