hibernate/hibernate-orm · error · IllegalArgumentException

Unable to determine JAR Url from <url>. Cause: <cause>

Error message

Unable to determine JAR Url from <url>. Cause: <cause>

What it means

ArchiveHelper.getJarURLFromURLEntry reconstructs the containing JAR's URL from the URL of a resource inside that jar (used during class/mapping scanning). When the entry URL's protocol, host, or file part cannot be reassembled into a well-formed URL, the MalformedURLException is wrapped in IllegalArgumentException. This almost always involves non-standard URL protocols or stream handlers supplied by application servers and containers.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java:120

					jarUrl = new File(file).toURL();
				}
			}
			else {
				try {
					//We reconstruct the URL probably to make it work in some specific environments
					//Forgot the exact details, sorry (and the Git history does not help)
					jarUrl = new URL( protocol, url.getHost(), url.getPort(), file );
				}
				//HHH-6442: Arquilian
				catch ( final MalformedURLException e ) {
					//Just use the provided URL as-is, likely it has a URLStreamHandler
					//associated w/ the instance
					jarUrl = url;
				}
			}
		}
		catch (MalformedURLException e) {
			throw new IllegalArgumentException(
					"Unable to determine JAR Url from " + url + ". Cause: " + e.getMessage()
			);
		}
		BOOT_LOGGER.jarUrlFromUrlEntry( String.valueOf(url), String.valueOf(jarUrl) );
		return jarUrl;
	}


	/// Attempt to resolve a `<jar-file/>` reference using a [ClassLoader].
	/// This form should only be used when we are parsing the `persistence.xml` ourselves
	/// and do not have an [ArchiveDescriptor].
	///
	/// @see org.hibernate.jpa.boot.internal.ParsedPersistenceXmlDescriptor
	public static URL resolveJarFileReference(String jarFileReference, URLClassLoader urlClassLoader) {
		assert jarFileReference != null;
		if ( jarFileReference.startsWith( "file://" ) ) {
			final var trimmed = jarFileReference.substring( "file://".length() );
			return asFileReference( jarFileReference, trimmed );

View on GitHub (pinned to fad1729dce)

Solutions

1. Upgrade Hibernate — archive/URL handling in ArchiveHelper has been fixed repeatedly across releases.
2. Bypass URL inference entirely: list entity classes explicitly (addAnnotatedClass or <class> entries in persistence.xml) so no jar-entry URL must be derived.
3. In containers, let the app server's JPA integration drive archive discovery instead of building MetadataSources manually.
4. Normalize the deployment path (remove spaces and unusual characters).

Example fix

// before: rely on automatic jar scanning over container URLs
MetadataSources sources = new MetadataSources(registry);
sources.addPackage("com.acme.model");

// after: enumerate classes explicitly, no jar URL inference needed
MetadataSources sources = new MetadataSources(registry);
sources.addAnnotatedClass(com.acme.model.Customer.class);
sources.addAnnotatedClass(com.acme.model.Order.class);

try {
    sources.addPackage("com.acme.model"); // triggers archive scanning
} catch (IllegalArgumentException e) {
    if (String.valueOf(e.getMessage()).startsWith("Unable to determine JAR Url")) {
        // fallback: no jar-URL inference, register classes explicitly
        sources.addAnnotatedClass(com.acme.model.Customer.class);
        sources.addAnnotatedClass(com.acme.model.Order.class);
    } else { throw e; }
}

When it happens

Trigger: Hibernate scans an annotated-classes archive whose entry URL uses a container protocol (vfs:, zip:, wsjar:, bundle:) or has a file part that breaks URL construction, so new URL(protocol, host, port, file) throws MalformedURLException.

Common situations: JBoss/WildFly VFS deployments, WebSphere wsjar URLs, WebLogic zip URLs, OSGi bundles; nested/uber-jars scanned by Hibernate's archive code; deployment paths with characters that need escaping.

Related errors

• Unable to convert jar File to URL [<jarFileReference>]
• Could not resolve jar-file: <jarFileReference>
• Could not find specified jar-file: <jarFileReference>
• Could not access specified jar-file: <jarFileReference>
• Unable to extract bytes from InputStream

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