hibernate/hibernate-orm · error · ConfigurationException

Unable to build hbm.xml JAXBContext

Error message

Unable to build hbm.xml JAXBContext

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/MappingBinder.java:198

						origin
				);

				//noinspection unchecked
				return new Binding<>( (X) bindingRoot, origin );
			}
			catch (JpaOrmXmlEventReader.BadVersionException e) {
				throw new UnsupportedOrmXsdVersionException( e.getRequestedVersion(), origin );
			}
		}
	}

	private JAXBContext hbmJaxbContext() {
		if ( hbmJaxbContext == null ) {
			try {
				hbmJaxbContext = JAXBContext.newInstance( JaxbHbmHibernateMapping.class );
			}
			catch (JAXBException e) {
				throw new ConfigurationException( "Unable to build hbm.xml JAXBContext", e );
			}
		}
		return hbmJaxbContext;
	}

	@Internal
	public JAXBContext mappingJaxbContext() {
		if ( entityMappingsJaxbContext == null ) {
			try {
				entityMappingsJaxbContext = JAXBContext.newInstance( JaxbEntityMappingsImpl.class );
			}
			catch (JAXBException e) {
				throw new ConfigurationException( "Unable to build orm.xml JAXBContext", e );
			}
		}
		return entityMappingsJaxbContext;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Add a compatible JAXB runtime: jakarta.xml.bind-api plus org.glassfish.jaxb:jaxb-runtime (match the version Hibernate's BOM pulls)
2. Run a dependency tree and exclude conflicting javax.xml.bind / old glassfish or moxy JAXB artifacts
3. Stop shading hibernate-core and its JAXB dependencies into a minimized uber-jar, or add keep rules for META-INF/services and jaxb classes

Example fix

<!-- before: no jaxb runtime on JDK 17 -->
<dependency>
  <groupId>org.hibernate.orm</groupId>
  <artifactId>hibernate-core</artifactId>
</dependency>

<!-- after -->
<dependency>
  <groupId>org.hibernate.orm</groupId>
  <artifactId>hibernate-core</artifactId>
</dependency>
<dependency>
  <groupId>org.glassfish.jaxb</groupId>
  <artifactId>jaxb-runtime</artifactId>
  <version>4.0.5</version>
</dependency>

try {
    jakarta.xml.bind.JAXBContext.newInstance(org.hibernate.boot.jaxb.hbm.spi.JaxbHbmHibernateMapping.class);
} catch (jakarta.xml.bind.JAXBException e) {
    throw new IllegalStateException("JAXB runtime unusable - fix classpath before bootstrap", e);
}

catch (ConfigurationException e) {
    if (e.getCause() instanceof jakarta.xml.bind.JAXBException) {
        // classpath/JAXB-runtime problem, not a mapping problem: report dependency conflict
        throw new IllegalStateException("JAXB runtime conflict - audit dependency:tree for duplicate JAXB providers", e);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to build orm.xml JAXBContext
• Unknown type of binding : <bindingRoot>
• Unable to create StAX reader
• Error accessing StAX stream
• Could not locate root element

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