hibernate/hibernate-orm · error · XmlInfrastructureException

Unable to load schema [${schemaUrl}]

Error message

Unable to load schema [${schemaUrl}]

What it means

After successfully opening the schema URL, LocalSchemaLocator hands the stream to SchemaFactory.newInstance(W3C_XML_SCHEMA_NS_URI).newSchema(...); any failure there is wrapped as XmlInfrastructureException 'Unable to load schema [url]'. The XSD stream was readable but could not be compiled into a javax.xml.validation.Schema — corrupt schema bytes or a broken JAXP parser configuration.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/stax/LocalSchemaLocator.java:55

		if ( url == null ) {
			throw new XmlInfrastructureException( "Unable to locate schema [" + schemaResourceName + "] via classpath" );
		}
		return url;
	}

	public static Schema resolveLocalSchema(String schemaName){
		return resolveLocalSchema( resolveLocalSchemaUrl( schemaName ) );
	}

	public static Schema resolveLocalSchema(URL schemaUrl) {
		try {
			final var schemaStream = schemaUrl.openStream();
			try {
				return SchemaFactory.newInstance( W3C_XML_SCHEMA_NS_URI )
						.newSchema( new StreamSource( schemaUrl.openStream() ) );
			}
			catch ( Exception e ) {
				throw new XmlInfrastructureException( "Unable to load schema [" + schemaUrl.toExternalForm() + "]", e );
			}
			finally {
				try {
					schemaStream.close();
				}
				catch ( IOException e ) {
					JAXB_LOGGER.problemClosingSchemaStream( e.toString() );
				}
			}
		}
		catch ( IOException e ) {
			throw new XmlInfrastructureException( "Stream error handling schema url [" + schemaUrl.toExternalForm() + "]" );
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

  1. Check dependency tree for xml-apis, xerces, xercesImpl and exclude old versions so the JDK parser is used
  2. Disable Maven resource filtering for .xsd files (or filter only on specific extensions)
  3. Verify the schema loads standalone: SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI).newSchema(new File("mapping.xsd")) in a test
  4. Re-download a pristine hibernate-core if the jar is damaged

Example fix

<!-- before (maven) -->
<resources><resource><directory>src/main/resources</directory><filtering>true</filtering></resource></resources>

<!-- after -->
<resources><resource><directory>src/main/resources</directory><filtering>true</filtering><excludes><exclude>**/*.xsd</exclude></excludes></resource></resources>
Defensive patterns

Strategy: validation

Validate before calling

try {
    javax.xml.validation.SchemaFactory
        .newInstance(javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI)
        .newSchema(new org.xml.sax.InputSource(new StringReader("<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'/>")));
} catch (org.xml.sax.SAXException e) {
    throw new IllegalStateException("JAXP parser configuration broken - check xerces/xml-apis conflicts", e);
}

Try / catch

catch (XmlInfrastructureException e) {
    throw new IllegalStateException("Cannot compile bundled XSD - likely corrupt resource or conflicting XML parser jars", e);
}

Prevention

When it happens

Trigger: XSD resource corrupted in the artifact (e.g. Maven resource filtering tokenized/mangled the .xsd text), or conflicting JAXP implementations (old xerces/xml-apis jars overriding the JDK parser) so SchemaFactory cannot instantiate a working validator; partially written hibernate-core jar.

Common situations: Resource filtering enabled for all files in a repackaged jar breaking binary/text XSDs; legacy xercesInternal/xml-apis 1.x on the classpath in old app-server stacks; antivirus or download corruption of the jar.

Related errors

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