hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized JPA orm.xml XSD version : `{}`

Error message

Unrecognized JPA orm.xml XSD version : `{}`

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/xsd/MappingXsdSupport.java:141

				return jpa21;
			}
			case "2.2": {
				return jpa22;
			}
			case "3.0:": {
				return jpa30;
			}
			case "3.1:": {
				return jpa31;
			}
			case "3.2:": {
				return jpa32;
			}
			case "4.0": {
				return jpa40;
			}
			default: {
				throw new IllegalArgumentException( "Unrecognized JPA orm.xml XSD version : `" + version + "`" );
			}
		}
	}

	public XsdDescriptor hbmXsd() {
		return hbmXml;
	}

}

View on GitHub (pinned to fad1729dce)

Solutions

1. 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.
2. 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).
3. Upgrade hibernate-core (or fix forward) if you must pass plain "3.0"/"3.1"/"3.2" strings and your build rejects them.
4. Validate version strings from user input/config against a whitelist before they reach Hibernate.

Example fix

// before
XsdDescriptor xsd = mappingXsdSupport.jpaXsd( "3.1" ); // this build's label is "3.1:" -> throws

// after
XsdDescriptor xsd = mappingXsdSupport.jpaXsd( "4.0" ); // or the exact label your build accepts
// defensive normalization:
String v = switch ( requested.trim() ) { case "3.0" -> "3.0:"; case "3.1" -> "3.1:"; case "3.2" -> "3.2:"; default -> requested.trim(); };

// accepted labels per MappingXsdSupport.jpaXsd switch in this build
private static final Set<String> SUPPORTED_ORM_XML_VERSIONS =
        Set.of( "1.0", "2.0", "2.1", "2.2", "3.0:", "3.1:", "3.2:", "4.0" );

static String normalizeOrmVersion(String raw) {
    String t = raw == null ? null : raw.trim();
    if ( t == null ) return null;
    return switch ( t ) { case "3.0" -> "3.0:"; case "3.1" -> "3.1:"; case "3.2" -> "3.2:"; default -> t; };
}

static boolean isSupportedJpaOrmXmlVersion(String v) {
    return v != null && Set.of( "1.0","2.0","2.1","2.2","3.0:","3.1:","3.2:","4.0" ).contains( v );
}

try { return mappingXsdSupport.jpaXsd( requested ); }
catch ( IllegalArgumentException e ) {
    if ( e.getMessage().startsWith( "Unrecognized JPA orm.xml XSD version" ) ) {
        return mappingXsdSupport.jpaXsd( normalizeOrmVersion( requested ) );
    }
    throw e;
}

When it happens

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

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

Related errors

• Unrecognized JPA persistence.xml XSD version : `{}`
• Stream error handling schema url [%s]
• Named query definition name is null: %s
• Named native query definition name is null: {}
• Result-set mapping name is null: {}

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