{"record":{"id":"64084b90ddc0796c","repo":"hibernate/hibernate-orm","slug":"unable-to-build-hbm-xml-jaxbcontext","errorCode":null,"errorMessage":"Unable to build hbm.xml JAXBContext","messagePattern":"Unable to build hbm\\.xml JAXBContext","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/MappingBinder.java","lineNumber":198,"sourceCode":"\t\t\t\t\t\torigin\n\t\t\t\t);\n\n\t\t\t\t//noinspection unchecked\n\t\t\t\treturn new Binding<>( (X) bindingRoot, origin );\n\t\t\t}\n\t\t\tcatch (JpaOrmXmlEventReader.BadVersionException e) {\n\t\t\t\tthrow new UnsupportedOrmXsdVersionException( e.getRequestedVersion(), origin );\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate JAXBContext hbmJaxbContext() {\n\t\tif ( hbmJaxbContext == null ) {\n\t\t\ttry {\n\t\t\t\thbmJaxbContext = JAXBContext.newInstance( JaxbHbmHibernateMapping.class );\n\t\t\t}\n\t\t\tcatch (JAXBException e) {\n\t\t\t\tthrow new ConfigurationException( \"Unable to build hbm.xml JAXBContext\", e );\n\t\t\t}\n\t\t}\n\t\treturn hbmJaxbContext;\n\t}\n\n\t@Internal\n\tpublic JAXBContext mappingJaxbContext() {\n\t\tif ( entityMappingsJaxbContext == null ) {\n\t\t\ttry {\n\t\t\t\tentityMappingsJaxbContext = JAXBContext.newInstance( JaxbEntityMappingsImpl.class );\n\t\t\t}\n\t\t\tcatch (JAXBException e) {\n\t\t\t\tthrow new ConfigurationException( \"Unable to build orm.xml JAXBContext\", e );\n\t\t\t}\n\t\t}\n\t\treturn entityMappingsJaxbContext;\n\t}\n}","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/MappingBinder.java#L180-L216","documentation":"A ConfigurationException thrown when JAXBContext.newInstance(JaxbHbmHibernateMapping.class) fails while Hibernate prepares to bind hbm.xml documents. The underlying JAXBException almost always means the JAXB runtime itself cannot initialize (missing API/implementation or conflicting implementations), not that your hbm.xml is wrong.","triggerScenarios":"Any bootstrap that binds an hbm.xml mapping: JAXB API missing from the classpath (Java 11+ removed javax/jakarta XML Bind from the JDK), two incompatible JAXB implementations (javax.xml.bind vs jakarta.xml.bind, or glassfish-jaxb vs moxy) fighting over the ServiceLoader, or shading/minimization stripping JAXB provider classes.","commonSituations":"Running on JDK 11+ without an explicit jaxb-runtime dependency; fat jars built with minimizeJar; application servers injecting their own JAXB version; adding cx-​friends style javax bridges alongside jakarta ones.","solutions":["Add a compatible JAXB runtime: jakarta.xml.bind-api plus org.glassfish.jaxb:jaxb-runtime (match the version Hibernate's BOM pulls)","Run a dependency tree and exclude conflicting javax.xml.bind / old glassfish or moxy JAXB artifacts","Stop shading hibernate-core and its JAXB dependencies into a minimized uber-jar, or add keep rules for META-INF/services and jaxb classes"],"exampleFix":"<!-- before: no jaxb runtime on JDK 17 -->\n<dependency>\n  <groupId>org.hibernate.orm</groupId>\n  <artifactId>hibernate-core</artifactId>\n</dependency>\n\n<!-- after -->\n<dependency>\n  <groupId>org.hibernate.orm</groupId>\n  <artifactId>hibernate-core</artifactId>\n</dependency>\n<dependency>\n  <groupId>org.glassfish.jaxb</groupId>\n  <artifactId>jaxb-runtime</artifactId>\n  <version>4.0.5</version>\n</dependency>","handlingStrategy":"validation","validationCode":"try {\n    jakarta.xml.bind.JAXBContext.newInstance(org.hibernate.boot.jaxb.hbm.spi.JaxbHbmHibernateMapping.class);\n} catch (jakarta.xml.bind.JAXBException e) {\n    throw new IllegalStateException(\"JAXB runtime unusable - fix classpath before bootstrap\", e);\n}","typeGuard":null,"tryCatchPattern":"catch (ConfigurationException e) {\n    if (e.getCause() instanceof jakarta.xml.bind.JAXBException) {\n        // classpath/JAXB-runtime problem, not a mapping problem: report dependency conflict\n        throw new IllegalStateException(\"JAXB runtime conflict - audit dependency:tree for duplicate JAXB providers\", e);\n    }\n    throw e;\n}","preventionTips":["Use the Hibernate BOM so jaxb-api and runtime versions stay aligned","Audit dependency:tree for javax.xml.bind, com.sun.xml.bind, moxy duplicates","Smoke-test SessionFactory bootstrap in CI on the same JDK as production"],"tags":["jaxb","classpath","hbm-xml","bootstrap","java-11"],"backgroundTag":"jaxb-runtime-missing","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}