hibernate/hibernate-orm · error · IllegalArgumentException

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

Error message

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

What it means

ConfigXsdSupport.jpaXsd(String) maps an explicit JPA version string to the cached persistence.xml XsdDescriptor. The switch accepts exactly "1.0", "2.0", "2.1", "2.2", "3.0", "3.1", "3.2", "4.0"; any other string (typo, padded whitespace, locale decimal like "2,1", or a version newer than this Hibernate knows, e.g. "5.0") falls into default and throws IllegalArgumentException.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/xsd/ConfigXsdSupport.java:84

				return getJPA21();
			}
			case "2.2": {
				return getJPA22();
			}
			case "3.0": {
				return getJPA30();
			}
			case "3.1": {
				return getJPA31();
			}
			case "3.2": {
				return getJPA32();
			}
			case "4.0": {
				return getJPA40();
			}
			default: {
				throw new IllegalArgumentException( "Unrecognized JPA persistence.xml XSD version : `" + version + "`" );
			}
		}
	}

	public static XsdDescriptor cfgXsd() {
		final int index = 0;
		synchronized ( xsdCache ) {
			XsdDescriptor cfgXml = xsdCache[index];
			if ( cfgXml == null ) {
				cfgXml = LocalXsdResolver.buildXsdDescriptor(
						"org/hibernate/xsd/cfg/legacy-configuration-4.0.xsd",
						"4.0" ,
						"http://www.hibernate.org/xsd/orm/cfg"
				);
				xsdCache[index] = cfgXml;
			}
			return cfgXml;
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use one of the supported exact strings: 1.0, 2.0, 2.1, 2.2, 3.0, 3.1, 3.2, 4.0.
2. Normalize before calling: trim whitespace, strip patch suffixes ("3.1.0" -> "3.1"), and reject comma decimals early.
3. If you genuinely need a newer JPA XSD, upgrade hibernate-core to a release whose ConfigXsdSupport knows that version.
4. Validate external version inputs against a whitelist before they reach Hibernate.

Example fix

// before
XsdDescriptor xsd = configXsdSupport.jpaXsd( requestedVersion ); // requestedVersion = "3.1.0" -> throws

// after
String v = requestedVersion.trim().replaceAll( "^(\\d+\\.\\d+).*$", "$1" );
if ( !Set.of( "1.0","2.0","2.1","2.2","3.0","3.1","3.2","4.0" ).contains( v ) ) {
    throw new IllegalArgumentException( "Unsupported JPA version: " + requestedVersion );
}
XsdDescriptor xsd = configXsdSupport.jpaXsd( v );

private static final Set<String> SUPPORTED_PERSISTENCE_XML_VERSIONS =
        Set.of( "1.0", "2.0", "2.1", "2.2", "3.0", "3.1", "3.2", "4.0" );

static String normalizeJpaVersion(String raw) {
    String v = raw == null ? null : raw.trim().replaceAll( "^(\\d+\\.\\d+).*$", "$1" );
    if ( !SUPPORTED_PERSISTENCE_XML_VERSIONS.contains( v ) )
        throw new IllegalArgumentException( "Unsupported persistence.xml version: " + raw );
    return v;
}

static boolean isSupportedJpaPersistenceXmlVersion(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 configXsdSupport.jpaXsd( requested ); }
catch ( IllegalArgumentException e ) {
    if ( e.getMessage().startsWith( "Unrecognized JPA persistence.xml XSD version" ) ) {
        return configXsdSupport.jpaXsd( normalizeJpaVersion( requested ) );
    }
    throw e;
}

When it happens

Trigger: Calling ConfigXsdSupport.jpaXsd(version) (directly or via bootstrap code that resolves a requested persistence.xml XSD version) with a string outside the supported set - for example "2.1 ", "3.0.0", "JPA 3.1", or a future version on an older hibernate-core.

Common situations: Passing a user-supplied or config-file-derived version string straight into the API without normalizing; upgrading the persistence.xsd version attribute ahead of upgrading Hibernate; regional settings producing comma decimals; integrations hardcoding versions this build does not know.

Related errors

• Unrecognized JPA orm.xml XSD version : `{}`
• Could not resolve jar-file: <jarFileReference>
• Unable to resolve <jar-file/> reference - {}
• Not supported.
• Stream error handling schema url [%s]

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