hibernate/hibernate-orm · error · XmlInfrastructureException

Unable to locate schema [${schemaResourceName}] via classpat

Error message

Unable to locate schema [${schemaResourceName}] via classpath

What it means

LocalSchemaLocator.resolveLocalSchemaUrl looks up a bundled XSD (e.g. org/hibernate/xsd/...) through hibernate-core's own classloader; a null result throws XmlInfrastructureException 'Unable to locate schema [name] via classpath'. This is an infrastructure defect: the XSD resources that ship inside hibernate-core are not visible where Hibernate is running.

Source

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

 *
 * @author Steve Ebersole
 */
public class LocalSchemaLocator {

	private LocalSchemaLocator() {
		// Disallow direct instantiation
	}

	/**
	 * Given the resource name of a schema, locate its URL reference via ClassLoader lookup.
	 *
	 * @param schemaResourceName The local resource name to the schema
	 *
	 */
	public static URL resolveLocalSchemaUrl(String schemaResourceName) {
		final URL url = LocalSchemaLocator.class.getClassLoader().getResource( schemaResourceName );
		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 );
			}

View on GitHub (pinned to fad1729dce)

Solutions

  1. Inspect the packaged artifact: 'jar tf app.jar | grep hibernate/xsd' — if the .xsd entries are gone, fix the build
  2. Add keep/include rules for **/*.xsd (and META-INF) to your shade/minimize configuration
  3. Use an unmodified hibernate-core artifact; if a local repo copy is truncated, delete it and re-resolve
  4. In isolated classloader setups, ensure the loader that loads hibernate-core can also getResource() its own jar entries

Example fix

<!-- before (shade plugin) -->
<minimizeJar>true</minimizeJar>

<!-- after -->
<minimizeJar>true</minimizeJar>
<filters>
  <filter>
    <artifact>org.hibernate.orm:hibernate-core</artifact>
    <includes>
      <include>**/*.xsd</include>
    </includes>
  </filter>
</filters>
Defensive patterns

Strategy: validation

Validate before calling

if (org.hibernate.boot.jaxb.internal.stax.LocalSchemaLocator.class
        .getClassLoader().getResource("org/hibernate/xsd/mapping/mapping-3.1.xsd") == null) {
    throw new IllegalStateException("hibernate-core XSDs missing from classpath - fix shading/minimization");
}

Try / catch

catch (XmlInfrastructureException e) {
    throw new IllegalStateException("Hibernate infrastructure broken: bundled XSDs not visible - inspect the packaged jar", e);
}

Prevention

When it happens

Trigger: Booting Hibernate in an environment where hibernate-core's resources were stripped or isolated: maven-shade minimizeJar or Gradle minimization dropping .xsd files, ProGuard stripping 'non-class' resources, aggressive classloader isolation (OSGi/PDE, custom module loaders) that cannot see resources from hibernate-core's jar.

Common situations: Uber-jar builds that minimize; embedded containers repackaging Hibernate; IDE runtimes with filtered resource output; a broken/partial hibernate-core jar in the local repository.

Related errors

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