hibernate/hibernate-orm · error · MappingNotFoundException

Invalid URL

Error message

Invalid URL

What it means

When opening a URL-based mapping, UrlXmlSource.fromUrl catches UnknownHostException specifically and throws MappingNotFoundException('Invalid URL'). It means the host part of the URL could not be resolved by DNS at bootstrap time — the URL syntax parsed, but the name lookup failed.

Source

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

	}

	/**
	 * 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. Verify name resolution on the deploy host: 'nslookup db.acme.internal' or InetAddress.getByName(host) in the same JVM
2. Fix the hostname in the URL or add the host to DNS/hosts file
3. Configure JVM proxy settings (-Dhttp.proxyHost/-Dhttp.proxyPort) if resolution goes through a proxy
4. Prefer packaging the mapping inside the app and using addResource/addClass instead of a remote HTTP URL

Example fix

// before
sessionFactoryCfg.addURL(new URL("http://acme-intrenal/mappings/item.hbm.xml")); // typo

// after
sessionFactoryCfg.addURL(new URL("http://acme-internal/mappings/item.hbm.xml"));

URL url = new URL("http", host, port, path);
try {
    InetAddress.getByName(url.getHost()); // throws UnknownHostException early, with a clearer message
} catch (UnknownHostException e) {
    throw new IllegalStateException("mapping host unresolvable: " + url.getHost(), e);
}
sessionFactoryCfg.addURL(url);

catch (MappingNotFoundException e) {
    if ("Invalid URL".equals(e.getMessage())) {
        throw new IllegalStateException("Host in mapping URL cannot be resolved - check DNS/proxy for the bootstrap host", e);
    }
    throw e;
}

When it happens

Trigger: Configuration.addURL(new URL("http://db.acme.internal/mappings/item.hbm.xml")) where the hostname does not resolve: typo'd host, internal DNS name unreachable from the deployment network, offline/air-gapped environment, or missing proxy configuration for HTTP-based mapping URLs.

Common situations: Mappings served over HTTP in environments with strict DNS; hostname valid in dev but not in the production subnet; JVM proxy properties (http.proxyHost) not set so the name is resolved locally and fails.

Related errors

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

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