hibernate/hibernate-orm · error · XsdException

Unable to load schema [{}]

Error message

Unable to load schema [{}]

What it means

The schema resource was located, but SchemaFactory.newSchema() threw SAXException, or opening its stream threw IOException. That means the bytes behind the URL are not a parseable W3C XML Schema - the resource exists but is damaged, truncated, or not actually XSD content. Hibernate wraps the failure in XsdException with the resource name and original cause.

Source

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

		}

		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() );
				}
			}
		}
		catch ( IOException e ) {
			throw new XsdException( "Stream error handling schema url [" + url.toExternalForm() + "]", schemaResourceName );
		}
	}

	public static XsdDescriptor buildXsdDescriptor(String resourceName, String version, String namespaceUri) {
		return new XsdDescriptor( resourceName, resolveLocalXsdSchema( resourceName ), version, namespaceUri );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Open the URL from the message and try loading it with a plain XML parser - confirm the content is a valid XSD.
2. Check for classpath shadowing: another artifact providing the same resource path earlier in resolution order; remove or fix it.
3. Disable resource filtering/minification for *.xsd files in the build and rebuild the jar.
4. Re-fetch hibernate-core from a trusted repository after verifying its checksum, then clean the local cache entry.

Example fix

# before
# maven-resources filtering applied to all files, corrupting hibernate's xsd
<resource><directory>...</directory><filtering>true</filtering></resource>

# after
<resource><directory>...</directory><filtering>true</filtering><excludes><exclude>**/*.xsd</exclude></excludes></resource>

static boolean parsesAsSchema(String resource) {
    URL url = Thread.currentThread().getContextClassLoader().getResource( resource );
    if ( url == null ) return false;
    try ( var in = url.openStream() ) {
        SchemaFactory.newInstance( XMLConstants.W3C_XML_SCHEMA_NS_URI ).newSchema( new StreamSource( in ) );
        return true;
    }
    catch ( Exception e ) { return false; }
}

try { return LocalXsdResolver.resolveLocalXsdSchema( name ); }
catch ( XsdException e ) {
    if ( e.getMessage().startsWith( "Unable to load schema" ) && e.getCause() instanceof SAXException sax ) {
        // resource present but corrupt -> verify jar checksum, look for shadowing resource
        reportCorruptedArtifact( name, sax );
    }
    throw e;
}

When it happens

Trigger: resolveLocalXsdSchema() on a schema whose stream yields invalid/corrupted XML: jar damaged in transit or by re-packaging, a filtering/templating build step that mangled the XSD text, or a same-named resource earlier on the classpath shadowing Hibernate's bundled one.

Common situations: Maven resource filtering enabled for the shaded jar (placeholder substitution corrupting schema files); a broken mirror serving a truncated hibernate-core jar; a project shipping its own org/hibernate/xsd/... file that gets resolved first; disk/full-cache corruption in an artifact repository.

Related errors

• Stream error handling schema url [{}]
• SingleStore does not support dropping creating/dropping sche
• Stream error handling schema url [%s]
• Unrecognized JPA persistence.xml XSD version : `{}`
• Unable to locate schema [{}] via classpath

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