hibernate/hibernate-orm · error · MappingException

Unable to open URL InputStream

Error message

Unable to open URL InputStream

What it means

In UrlXmlSource.fromUrl, any IOException from url.openStream() other than UnknownHostException is wrapped as MappingException('Unable to open URL InputStream'). The stream-level open failed: HTTP error status (FileNotFoundException for 404), connection refused, timeout, or an unreadable file: URL.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/UrlXmlSource.java:77

	 * Create a mapping {@linkplain Binding binding} from a URL
	 *
	 * @param url The url from which to read the mapping information
	 * @param origin Description of the source from which the url came
	 * @param binder The JAXB binder to use
	 */
	public static Binding<? extends JaxbBindableMappingDescriptor> fromUrl(
			URL url,
			Origin origin,
			MappingBinder binder) {
		JAXB_LOGGER.tracef( "Reading mapping document from URL: %s", origin.getName() );
		try {
			return InputStreamXmlSource.fromStream( url.openStream(), origin, true, binder );
		}
		catch (UnknownHostException e) {
			throw new MappingNotFoundException( "Invalid URL", e, origin );
		}
		catch (IOException e) {
			throw new MappingException( "Unable to open URL InputStream", e, origin );
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Test the exact URL from the deploy host: 'curl -fO http://host/mappings/item.hbm.xml'
2. Fix the path (404) or grant read permission (file URLs), or start/unchblock the serving host
3. Set -Dsun.net.client.defaultConnectTimeout if slow networks cause hangs
4. Move the mapping into the artifact and load it via addResource to remove the network dependency from bootstrap

Example fix

// before
sessionFactoryCfg.addURL(new URL("file:/opt/cfg/mapping/item.hbm.xml")); // file missing

// after: keep mapping inside the jar, no runtime file dependency
sessionFactoryCfg.addResource("mappings/item.hbm.xml");

try (InputStream probe = url.openStream()) {
    // reachable now; note this is the same operation Hibernate performs, so treat as fail-fast probe
} catch (IOException e) {
    throw new IllegalStateException("mapping URL not openable: " + url, e);
}

catch (MappingException e) {
    Throwable c = e.getCause();
    if (c instanceof java.io.FileNotFoundException) { /* 404 or missing file */ }
    else if (c instanceof java.net.ConnectException) { /* server down / refused */ }
    throw new IllegalStateException("Cannot open mapping URL " + url, e);
}

When it happens

Trigger: Configuration.addURL(...) where the server returns 404/403/500 (HttpURLConnection maps 404 to FileNotFoundException), the port is closed (connection refused), a file:// URL points to a missing/unreadable file, or a read timeout fires while the server stalls.

Common situations: Mapping served by an HTTP endpoint that is down or firewalled from the application subnet; file URL with wrong path or OS-level permission denied; slow CI network causing connect timeouts during bootstrap.

Related errors

• Invalid URL
• Unable to open InputStream for jar file entry [%s : %s]
• Mapping (%s) not found : %s
• Could not parse mapping document: %s (%s)
• Mapping (%s) not found : %s

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