hibernate/hibernate-orm · error · XsdException

Stream error handling schema url [%s]

Error message

Stream error handling schema url [%s]

What it means

Thrown by Hibernate's cfg.xml processor while it validates hibernate.cfg.xml. After resolving the XML schema (XSD) for the configuration file, opening or reading the schema's InputStream raised an IOException, which Hibernate wraps in an XsdException together with the schema URL. Note that the underlying IOException is not chained into this exception, so the message URL is your main diagnostic. The problem is that the schema itself could not be read, not that your cfg.xml syntax is wrong.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/cfgxml/internal/JaxbCfgProcessor.java:178

			final var schemaStream = url.openStream();
			try {
				return SchemaFactory.newInstance( schemaLanguage )
						.newSchema( new StreamSource( url.openStream() ) );
			}
			catch ( SAXException | IOException e ) {
				throw new XsdException( "Unable to load schema [" + schemaName + "]", e, schemaName );
			}
			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() + "]", schemaName );
		}
	}

	static class ContextProvidingValidationEventHandler implements ValidationEventHandler {
		private int lineNumber;
		private int columnNumber;
		private String message;

		@Override
		public boolean handleEvent(ValidationEvent validationEvent) {
			final var locator = validationEvent.getLocator();
			lineNumber = locator.getLineNumber();
			columnNumber = locator.getColumnNumber();
			message = validationEvent.getMessage();
			return false;
		}

		public int getLineNumber() {

View on GitHub (pinned to fad1729dce)

Solutions

1. Drop the remote xsi:schemaLocation and let Hibernate resolve the XSD bundled inside hibernate-core (namespace-only reference)
2. If you must keep the reference, add an XML catalog / entity resolver so the schema resolves from the classpath with no network fetch
3. Check proxy and firewall settings when the schema URL is genuinely remote and must be fetched
4. If building a fat jar, verify hibernate-core's schema resources survived shading and add them back if stripped

Example fix

<!-- before: schemaLocation forces a remote fetch -->
<hibernate-configuration xmlns="http://www.hibernate.org/xsd/orm/cfg"
    xsi:schemaLocation="http://www.hibernate.org/xsd/orm/cfg http://www.hibernate.org/xsd/orm/cfg/hibernate-configuration.xsd">

<!-- after: no remote schemaLocation, Hibernate uses the XSD bundled in hibernate-core -->
<hibernate-configuration xmlns="http://www.hibernate.org/xsd/orm/cfg">

// Fail fast before Configuration.configure(...)
try (InputStream in = new URL(schemaUrl).openStream()) {
    if (in == null) throw new IllegalStateException("cfg.xml schema unreachable: " + schemaUrl);
}
catch (IOException e) {
    throw new IllegalStateException("Schema URL not readable: " + schemaUrl
            + " - fix offline/proxy setup or use the bundled schema", e);
}

try {
    SessionFactory sf = new Configuration().configure("hibernate.cfg.xml").buildSessionFactory();
}
catch (XsdException e) {
    // The schema stream could not be opened/read: take the URL from e.getMessage(),
    // switch to the classpath-bundled schema or fix network/proxy access
}

When it happens

Trigger: JaxbCfgProcessor resolves the cfg.xml schema to a URL and opens a stream on it; any IOException while obtaining or reading that stream (unreachable remote XSD URL, missing classpath XSD resource, dropped connection, shaded jar that stripped the resource) falls into the catch at JaxbCfgProcessor.java:178 and is rethrown as XsdException.

Common situations: Air-gapped or firewalled environments where the schemaLocation forces an HTTP fetch of the XSD; uber-jars/shaded builds that leave hibernate-core's bundled XSD resources behind; a cfg.xml schema reference pointing at a URL that no longer resolves; partial Hibernate upgrades where the referenced schema version is not on the classpath.

Related errors

• Stream error handling schema url [{}]
• Unable to extract bytes from InputStream
• Unable to access stream from jar file [%s] for entry [%s]
• Error accessing jar file [<rootFilePath>]
• Unrecognized cache declaration

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