hibernate/hibernate-orm · error · XmlInfrastructureException

Stream error handling schema url [${schemaUrl}]

Error message

Stream error handling schema url [${schemaUrl}]

What it means

If schemaUrl.openStream() itself throws IOException, LocalSchemaLocator wraps it as XmlInfrastructureException 'Stream error handling schema url [url]' (note: no cause is attached). The schema URL resolved to something that can no longer be opened — the owning jar/file became unreadable between resolution and open.

Source

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

			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. Ensure hibernate-core's classloader/jar stays open for the whole life of the SessionFactory (rebuild factories after redeploy, not during)
2. Verify the containing jar/file still exists and is readable at bootstrap: Files.isReadable(Path.of(url.toURI()))
3. Retry bootstrap in a clean state after a hot redeploy instead of reusing cached metadata objects

URL xsd = LocalSchemaLocator.class.getClassLoader().getResource("org/hibernate/xsd/mapping/mapping-3.1.xsd");
if (xsd == null || !java.nio.file.Files.isReadable(java.nio.file.Path.of(xsd.toURI()))) {
    throw new IllegalStateException("bundled XSD unreadable before bootstrap");
}

catch (XmlInfrastructureException e) {
    throw new IllegalStateException("Schema stream could not be opened - owning jar/classloader may be closed; rebuild in a clean state", e);
}

When it happens

Trigger: The URLClassLoader or JarFile owning the XSD was closed before Hibernate binds mappings (dynamic module unloading, hot-redeploy), the containing file was deleted or its permissions changed, or an OS-level lock (Windows/antivirus) blocks opening the entry.

Common situations: Application servers that close child classloaders during redeploy while a cached SessionFactory rebuilds; temporary-file schemas deleted mid-bootstrap; exotic containerized setups with read-only mounts appearing after startup.

Related errors

• Stream error handling schema url [%s]
• Unable to open InputStream for jar file entry [%s : %s]
• Encountered unsupported orm.xml xsd version [{}]
• Unable to open URL InputStream
• Unable to locate schema [${schemaResourceName}] via classpat

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