{"record":{"id":"f5d3330d089afa73","repo":"hibernate/hibernate-orm","slug":"encountered-unsupported-orm-xml-xsd-version","errorCode":null,"errorMessage":"Encountered unsupported orm.xml xsd version [{}]","messagePattern":"Encountered unsupported orm\\.xml xsd version \\[(.+?)\\]","errorType":"exception","errorClass":"UnsupportedOrmXsdVersionException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/MappingBinder.java","lineNumber":187,"sourceCode":"\t\t\t//noinspection unchecked\n\t\t\treturn new Binding<>( (X) hbmBindings, origin );\n\t\t}\n\t\telse {\n\t\t\tassert \"entity-mappings\".equals( rootElementLocalName );\n\t\t\ttry {\n\t\t\t\tJAXB_LOGGER.performingJaxbBindingOfOrmXmlDocument( origin.toString() );\n\t\t\t\tfinal var bindingRoot = jaxb(\n\t\t\t\t\t\tnew MappingEventReader( staxEventReader, xmlEventFactory ),\n\t\t\t\t\t\tMappingXsdSupport.latestDescriptor().getSchema(),\n\t\t\t\t\t\tmappingJaxbContext(),\n\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() {","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/MappingBinder.java#L169-L205","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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+)","Upgrade hibernate-core to a release that ships the requested XSD","Run 'mvn dependency:tree' (or Gradle equivalent) and remove the stale hibernate-core artifact so only one version loads"],"exampleFix":"<!-- before -->\n<entity-mappings xmlns=\"https://jakarta.ee/xml/ns/persistence/orm\" version=\"3.2\">\n\n<!-- after (Hibernate 6.2-6.5) -->\n<entity-mappings xmlns=\"https://jakarta.ee/xml/ns/persistence/orm\" version=\"3.1\">","handlingStrategy":"validation","validationCode":"String v = rootElement.getAttribute(\"version\"); // parse orm.xml with DocumentBuilder first\nif (!SUPPORTED_ORM_VERSIONS.contains(v)) {\n    throw new IllegalStateException(\"orm.xml version \" + v + \" not supported by hibernate-core \" + Version.getVersionString());\n}","typeGuard":null,"tryCatchPattern":"catch (UnsupportedOrmXsdVersionException e) {\n    // e.getRequestedVersion() names the rejected version, e.getOrigin() the file\n    throw newConfigurationException(\"orm.xml declares \" + e.getRequestedVersion() + \" but Hibernate \" + Version.getVersionString() + \" does not support it\", e);\n}","preventionTips":["Manage hibernate-core and jakarta.persistence-api versions together via the Hibernate BOM","Add a build check comparing orm.xml version attributes against the runtime's supported set","Fail fast at startup smoke tests so version drift is caught in CI"],"tags":["jpa","orm-xml","xsd","version-mismatch","bootstrap"],"backgroundTag":"orm-xsd-version-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}