What causes "Unable to locate schema [{}] via classpath" in hibernate/hibernate-orm?

Verify the resource exists in the runtime classpath: inspect the hibernate-core jar for the schema path named in the message.

hibernate/hibernate-orm · error · XsdException

Unable to locate schema [{}] via classpath

Error message

Unable to locate schema [{}] via classpath

What it means

LocalXsdResolver loads the XSDs bundled inside hibernate-core (e.g. org/hibernate/xsd/...) by first locating the resource on the classpath via resolveLocalXsdUrl. If no URL can be produced, the resource simply is not visible to Hibernate's classloader, and XsdException('Unable to locate schema [...] via classpath') is thrown naming the missing resource.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/xsd/LocalXsdResolver.java:78

			catch (Exception ignore) {
			}
		}

		// Last: we try name as a URL
		try {
			return new URL( resourceName );
		}
		catch (Exception ignore) {
		}

		return null;
	}


	public static Schema resolveLocalXsdSchema(String schemaResourceName) {
		final URL url = resolveLocalXsdUrl( schemaResourceName );
		if ( url == null ) {
			throw new XsdException( "Unable to locate schema [" + schemaResourceName + "] via classpath", schemaResourceName );
		}
		try {
			final var schemaStream = url.openStream();
			try {
				return SchemaFactory.newInstance( W3C_XML_SCHEMA_NS_URI )
						.newSchema( new StreamSource( url.openStream() ) );
			}
			catch ( SAXException | IOException e ) {
				throw new XsdException( "Unable to load schema [" + schemaResourceName + "]", e, schemaResourceName );
			}
			finally {
				try {
					schemaStream.close();
				}
				catch ( IOException e ) {
					JAXB_LOGGER.problemClosingSchemaStream( e.toString() );
				}
			}

View on GitHub (pinned to fad1729dce)

Solutions

Verify the resource exists in the runtime classpath: inspect the hibernate-core jar for the schema path named in the message.
Stop shade/minimize tools from stripping XSDs (keep org/hibernate/xsd/** resource patterns; do not minimize hibernate-core).
Re-download/replace a corrupted hibernate-core artifact (checksum check) and pin a good version.
If using a custom ClassLoaderService, ensure it can serve Hibernate's own resources, or fix parent-delegation order in the app server.

Example fix

# before
# shade plugin without resource retention -> xsd files removed from hibernate-core
<filters><filter><artifact>*:*</artifact><excludes><exclude>**/*.xsd</exclude></excludes></filter></filters>

# after
# keep Hibernate's bundled schemas in the fat jar
<filters><filter><artifact>org.hibernate:hibernate-core</artifact><includes><include>**</include></includes></filter></filters>

Defensive patterns

Strategy: validation

Validate before calling

static boolean hibernateXsdsVisible() {
    ClassLoader cl = org.hibernate.boot.xsd.LocalXsdResolver.class.getClassLoader();
    return cl.getResource( "org/hibernate/xsd/cfg/legacy-configuration-4.0.xsd" ) != null
        && cl.getResource( "org/hibernate/xsd/mapping/orm_4_0.xsd" ) != null;
}
// run as a startup/deploy health check before building the SessionFactory

Try / catch

try { return LocalXsdResolver.resolveLocalXsdSchema( name ); }
catch ( XsdException e ) {
    if ( e.getMessage().startsWith( "Unable to locate schema" ) ) {
        throw new IllegalStateException( "hibernate-core jar incomplete - bundled XSDs missing: " + name, e );
    }
    throw e;
}

Prevention

Never strip **/*.xsd when shading/minimizing hibernate-core; test the fat jar's bootstrap in CI.
Add a startup assertion that Hibernate's own resources resolve from the runtime classloader.
Prevent classpath shadowing of org/hibernate/** resources by your own artifacts.

When it happens

Trigger: resolveLocalXsdSchema(schemaResourceName) called with a bundled schema name that the current ClassLoaderService cannot resolve: shaded/minimized hibernate-core jar from which the xsd resources were stripped, a broken dependency resolution, or a custom ClassLoaderService that hides resources.

Common situations: Maven/Gradle shade or proguard/R8 minification removing *.xsd resources from hibernate-core; app-server parent-first classloading isolating Hibernate from its own jar; corrupted or incompletely downloaded hibernate-core artifact; custom classloader service delegating to a loader without hibernate-core.

Related errors

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