{"record":{"id":"6b10df15c54cace4","repo":"hibernate/hibernate-orm","slug":"unknown-type-of-binding-bindingroot","errorCode":null,"errorMessage":"Unknown type of binding : <bindingRoot>","messagePattern":"Unknown type of binding : <bindingRoot>","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java","lineNumber":390,"sourceCode":"\t/**\n\t * Add XML mapping bindings created from an arbitrary source by the\n\t * {@linkplain #getXmlMappingBinderAccess() binder}.\n\t *\n\t * @param binding The binding\n\t *\n\t * @return this (for method chaining purposes)\n\t */\n\tpublic MetadataSources addXmlBinding(Binding<?> binding) {\n\t\tif ( binding.getRoot() instanceof JaxbEntityMappingsImpl ) {\n\t\t\t//noinspection unchecked\n\t\t\treturn addMappingXmlBinding( (Binding<JaxbEntityMappingsImpl>) binding );\n\t\t}\n\t\telse if ( binding.getRoot() instanceof JaxbHbmHibernateMapping ) {\n\t\t\t//noinspection unchecked\n\t\t\treturn addHbmXmlBinding( (Binding<JaxbHbmHibernateMapping>) binding );\n\t\t}\n\n\t\tthrow new UnsupportedOperationException( \"Unknown type of binding : \" + binding.getRoot() );\n\t}\n\n\t/**\n\t * Add a {@linkplain Binding binding} for {@linkplain JaxbEntityMappingsImpl mapping.xsd} document\n\t *\n\t * @param binding The binding\n\t *\n\t * @return this (for method chaining purposes)\n\t */\n\tpublic MetadataSources addMappingXmlBinding(Binding<JaxbEntityMappingsImpl> binding) {\n\t\tif ( mappingXmlBindings == null ) {\n\t\t\tmappingXmlBindings = new ArrayList<>();\n\t\t}\n\t\tmappingXmlBindings.add( binding );\n\t\treturn this;\n\t}\n\n\t/**","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/MetadataSources.java#L372-L408","documentation":"MetadataSources.addXmlBinding dispatches purely on the JAXB root element type: JaxbEntityMappingsImpl (orm.xml) routes to mapping-XML handling and JaxbHbmHibernateMapping (hbm.xml) to HBM handling. Any other root object is rejected with UnsupportedOperationException — the method exists only for Hibernate's own JAXB binding model.","triggerScenarios":"Passing a Binding whose root is neither model class: a JaxbPersistence (persistence.xml) object, a JAXB class from a different Hibernate version, or a custom-unmarshalled document.","commonSituations":"Custom bootstrap code that unmarshals XML itself and hands the Binding to Hibernate; two hibernate-core versions on the classpath making instanceof fail across classloaders; migrations across major versions where binding classes changed.","solutions":["Let Hibernate do the JAXB binding itself: use MetadataSources.addResource / addInputStream / addFile for XML mappings.","If you already hold a Binding, route it explicitly: addMappingXmlBinding for orm roots, addHbmXmlBinding for hbm roots.","Ensure a single hibernate-core version on the classpath so root classes match by identity."],"exampleFix":"// before\nsources.addXmlBinding(binding); // root is JaxbPersistence -> throws\n\n// after\nif (binding.getRoot() instanceof JaxbEntityMappingsImpl) {\n    sources.addMappingXmlBinding(binding);\n}\nelse if (binding.getRoot() instanceof JaxbHbmHibernateMapping) {\n    sources.addHbmXmlBinding(binding);\n}\nelse {\n    sources.addResource(\"META-INF/mappings.xml\"); // let Hibernate bind the XML\n}","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean isSupportedXmlBinding(Binding<?> binding) {\n    Object root = binding.getRoot();\n    return root instanceof JaxbEntityMappingsImpl\n            || root instanceof JaxbHbmHibernateMapping;\n}","tryCatchPattern":"Prefer routing by root type before calling the API; if you must call addXmlBinding blindly, catch UnsupportedOperationException and fall back to addResource so Hibernate performs the JAXB binding itself.","preventionTips":["Prefer MetadataSources.addResource/addInputStream over hand-built Binding objects.","Keep exactly one hibernate-core version so instanceof checks are reliable.","Do not feed persistence.xml objects into mapping-binding APIs."],"tags":["hibernate","jaxb","xml-mapping","bootstrap","unsupported-operation"],"backgroundTag":"unsupported-binding-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}