What causes "Stream error handling schema url [{}]" in hibernate/hibernate-orm?

Check the URL in the message and open it manually (curl/unzip) to see whether the entry truly exists and is readable in the failing environment.

hibernate/hibernate-orm · error · XsdException

Stream error handling schema url [{}]

Error message

Stream error handling schema url [{}]

What it means

After locating the schema URL and entering the loading block, the initial url.openStream() threw an IOException, which the outer catch converts to XsdException('Stream error handling schema url [...]') including the external form of the URL. The resource was resolvable as a URL, but the stream could not be opened at all - a connection/I-O level failure rather than a parse failure.

Source

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

			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

Check the URL in the message and open it manually (curl/unzip) to see whether the entry truly exists and is readable in the failing environment.
For intermittent I/O on shared caches, retry after warming/re-downloading artifacts; pin artifacts locally to avoid mid-boot rewrites.
Avoid redeploys that mutate classpath jars during startup (staging the new jar then switching atomically).
If a custom protocol handler is involved, ensure it supports openStream() or fall back to standard jar/file protocols.

Example fix

// before
// jar replaced while SessionFactory builds -> url.openStream() throws IOException
new SchemaFactory... // bootstrap fails with 'Stream error handling schema url [jar:file:...hibernate-core.jar!/...]'

// after
// stage artifacts immutably and build from a stable classpath
cp $(readlink -f libs/hibernate-core.jar):... com.acme.App
// verify readability before boot:
try ( var in = url.openStream() ) { in.readAllBytes(); }

Defensive patterns

Strategy: try-catch

Validate before calling

static boolean schemaStreamOpenable(String resource) {
    URL url = Thread.currentThread().getContextClassLoader().getResource( resource );
    if ( url == null ) return false;
    try ( var ignored = url.openStream() ) { return true; }
    catch ( IOException e ) { return false; }
}

Try / catch

try { return LocalXsdResolver.resolveLocalXsdSchema( name ); }
catch ( XsdException e ) {
    if ( e.getMessage().startsWith( "Stream error handling schema url" ) ) {
        // I/O-level failure on the resolved URL: stale/rewritten jar, unreadable entry, FS error
        retryOnceAfterRefreshingArtifacts( name ); // then rethrow if it persists
    }
    throw e;
}

Prevention

Keep the classpath immutable during startup - do not rewrite jars a running bootstrap is reading.
Use stable, read-only artifact caches in CI (content-addressed) to avoid mid-read cache mutation.
Health-check critical classpath resources (resolve + openStream) before bootstrap in restrictive environments.

When it happens

Trigger: resolveLocalXsdSchema() where url.openStream() fails: jar/entry deleted or replaced between resolution and opening, URL pointing at a remote/unreachable location, or a jar protocol handler denied by the environment (e.g. sealed runtime, security manager, sandboxed FS).

Common situations: Hot-redeploy or parallel build deleting/rewriting the jar that contains the schema while Hibernate bootstraps; custom URL schemes registered for the classpath; restrictive containers blocking jar: or file: access; NFS/cloud-mounted artifact caches with transient I/O errors.

Related errors

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