hibernate/hibernate-orm · error · UnsupportedOrmXsdVersionException

Encountered unsupported orm.xml xsd version [{}]

Error message

Encountered unsupported orm.xml xsd version [{}]

What it means

Hibernate throws UnsupportedOrmXsdVersionException when an orm.xml root element declares a version attribute that this hibernate-core build's bundled XSDs (MappingXsdSupport) do not know. JpaOrmXmlEventReader inspects the version attribute while streaming the document and raises BadVersionException, which MappingBinder rethrows with the requested version and Origin. It protects against silently binding a document written for a newer persistence API.

Source

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

			//noinspection unchecked
			return new Binding<>( (X) hbmBindings, origin );
		}
		else {
			assert "entity-mappings".equals( rootElementLocalName );
			try {
				JAXB_LOGGER.performingJaxbBindingOfOrmXmlDocument( origin.toString() );
				final var bindingRoot = jaxb(
						new MappingEventReader( staxEventReader, xmlEventFactory ),
						MappingXsdSupport.latestDescriptor().getSchema(),
						mappingJaxbContext(),
						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() {

View on GitHub (pinned to fad1729dce)

Solutions

1. Set the orm.xml version attribute to the highest version your deployed Hibernate supports (e.g. 3.1 for Hibernate 6.2-6.5, 3.2 for 6.6+)
2. Upgrade hibernate-core to a release that ships the requested XSD
3. Run 'mvn dependency:tree' (or Gradle equivalent) and remove the stale hibernate-core artifact so only one version loads

Example fix

<!-- before -->
<entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm" version="3.2">

<!-- after (Hibernate 6.2-6.5) -->
<entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm" version="3.1">

String v = rootElement.getAttribute("version"); // parse orm.xml with DocumentBuilder first
if (!SUPPORTED_ORM_VERSIONS.contains(v)) {
    throw new IllegalStateException("orm.xml version " + v + " not supported by hibernate-core " + Version.getVersionString());
}

catch (UnsupportedOrmXsdVersionException e) {
    // e.getRequestedVersion() names the rejected version, e.getOrigin() the file
    throw newConfigurationException("orm.xml declares " + e.getRequestedVersion() + " but Hibernate " + Version.getVersionString() + " does not support it", e);
}

When it happens

Trigger: Any orm.xml binding (SessionFactory bootstrap, persistence.xml <mapping-file>, MetadataBuilder) where <entity-mings version="X"> names an XSD unknown to the Hibernate version on the classpath — typically version="3.2" on a Hibernate that only supports up to 3.1/3.0, or a stale hibernate-core jar mixed with newer application code.

Common situations: Upgrading jakarta.persistence-api or the app server but not hibernate-core; duplicate hibernate-core versions on the classpath (old one wins); generating orm.xml with a newer toolchain than the runtime.

Related errors

• AttributeConverter class [%s] registered multiple times
• Named query definition name is null: %s
• Duplicate named query '%s'
• Named native query definition name is null: {}
• Duplicate named stored procedure '{}'

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