{"record":{"id":"7fc8d1f59afadd8a","repo":"hibernate/hibernate-orm","slug":"unrecognized-jpa-orm-xml-xsd-version","errorCode":null,"errorMessage":"Unrecognized JPA orm.xml XSD version : `{}`","messagePattern":"Unrecognized JPA orm\\.xml XSD version : `(.+?)`","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/xsd/MappingXsdSupport.java","lineNumber":141,"sourceCode":"\t\t\t\treturn jpa21;\n\t\t\t}\n\t\t\tcase \"2.2\": {\n\t\t\t\treturn jpa22;\n\t\t\t}\n\t\t\tcase \"3.0:\": {\n\t\t\t\treturn jpa30;\n\t\t\t}\n\t\t\tcase \"3.1:\": {\n\t\t\t\treturn jpa31;\n\t\t\t}\n\t\t\tcase \"3.2:\": {\n\t\t\t\treturn jpa32;\n\t\t\t}\n\t\t\tcase \"4.0\": {\n\t\t\t\treturn jpa40;\n\t\t\t}\n\t\t\tdefault: {\n\t\t\t\tthrow new IllegalArgumentException( \"Unrecognized JPA orm.xml XSD version : `\" + version + \"`\" );\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic XsdDescriptor hbmXsd() {\n\t\treturn hbmXml;\n\t}\n\n}\n","sourceCodeStart":123,"sourceCodeEnd":151,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/xsd/MappingXsdSupport.java#L123-L151","documentation":"MappingXsdSupport.jpaXsd(String) maps an explicit JPA version string to the orm.xml XsdDescriptor. Per this source, the switch labels are \"1.0\", \"2.0\", \"2.1\", \"2.2\", \"3.0:\", \"3.1:\", \"3.2:\", \"4.0\" - note the trailing-colon spellings for 3.0/3.1/3.2 in this build. Any other string hits default and throws IllegalArgumentException naming the rejected version.","triggerScenarios":"Calling MappingXsdSupport.jpaXsd(version) with a string that does not exactly match a case label: a plain \"3.1\"/\"3.2\"/\"3.0\" in a build whose labels carry the trailing colon, a padded or patch-suffixed version (\"2.1 \", \"3.1.0\"), or a version newer than this Hibernate knows.","commonSituations":"Tooling or integrations that derive the version string from an XML declaration/namespace (where a colon-suffixed token can appear) and pass it through verbatim; code written against a Hibernate whose labels were plain \"3.x\" later running on this colon-labelled variant (or vice versa); future JPA versions on an older build.","solutions":["Pass exactly the spellings this build accepts: \"1.0\", \"2.0\", \"2.1\", \"2.2\", \"3.0:\", \"3.1:\", \"3.2:\", \"4.0\" - or simply \"4.0\" for the latest.","Normalize inputs before calling: trim, and map bare \"3.x\" to the accepted label of your Hibernate version (check the switch in your build's MappingXsdSupport).","Upgrade hibernate-core (or fix forward) if you must pass plain \"3.0\"/\"3.1\"/\"3.2\" strings and your build rejects them.","Validate version strings from user input/config against a whitelist before they reach Hibernate."],"exampleFix":"// before\nXsdDescriptor xsd = mappingXsdSupport.jpaXsd( \"3.1\" ); // this build's label is \"3.1:\" -> throws\n\n// after\nXsdDescriptor xsd = mappingXsdSupport.jpaXsd( \"4.0\" ); // or the exact label your build accepts\n// defensive normalization:\nString v = switch ( requested.trim() ) { case \"3.0\" -> \"3.0:\"; case \"3.1\" -> \"3.1:\"; case \"3.2\" -> \"3.2:\"; default -> requested.trim(); };","handlingStrategy":"validation","validationCode":"// accepted labels per MappingXsdSupport.jpaXsd switch in this build\nprivate static final Set<String> SUPPORTED_ORM_XML_VERSIONS =\n        Set.of( \"1.0\", \"2.0\", \"2.1\", \"2.2\", \"3.0:\", \"3.1:\", \"3.2:\", \"4.0\" );\n\nstatic String normalizeOrmVersion(String raw) {\n    String t = raw == null ? null : raw.trim();\n    if ( t == null ) return null;\n    return switch ( t ) { case \"3.0\" -> \"3.0:\"; case \"3.1\" -> \"3.1:\"; case \"3.2\" -> \"3.2:\"; default -> t; };\n}","typeGuard":"static boolean isSupportedJpaOrmXmlVersion(String v) {\n    return v != null && Set.of( \"1.0\",\"2.0\",\"2.1\",\"2.2\",\"3.0:\",\"3.1:\",\"3.2:\",\"4.0\" ).contains( v );\n}","tryCatchPattern":"try { return mappingXsdSupport.jpaXsd( requested ); }\ncatch ( IllegalArgumentException e ) {\n    if ( e.getMessage().startsWith( \"Unrecognized JPA orm.xml XSD version\" ) ) {\n        return mappingXsdSupport.jpaXsd( normalizeOrmVersion( requested ) );\n    }\n    throw e;\n}","preventionTips":["Derive the version string from Hibernate itself (latestJpaDescriptor()) instead of hand-building strings when you just want 'current'.","Check the case labels of your build's MappingXsdSupport before passing 3.x version strings.","Treat version strings as opaque tokens validated against the running Hibernate, not free-form input."],"tags":["hibernate","xsd","orm-xml","version","validation"],"backgroundTag":"unsupported-xsd-version","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}