hibernate/hibernate-orm · error · ArchiveException

Unable to convert jar File to URL [<jarFileReference>]

Error message

Unable to convert jar File to URL [<jarFileReference>]

What it means

While building an ArchiveDescriptor from a jar reference, ArchiveHelper finds the file on disk but File.toURI().toURL() throws MalformedURLException, which is wrapped as ArchiveException 'Unable to convert jar File to URL'. Rare and environmental: the path exists yet cannot be turned into a well-formed URL by this JVM.

Source

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

	public static ArchiveDescriptor standardJarFileReferenceResolution(
			@Nonnull String jarFileReference,
			ArchiveDescriptorFactory archiveDescriptorFactory) {

		// try it as a URL
		final var asUrl = resolveJarFileReferenceAsUrl( jarFileReference, archiveDescriptorFactory );
		if ( asUrl != null ) {
			return asUrl;
		}

		// try it as a File path
		try {
			var file = new File( jarFileReference );
			if ( file.exists() ) {
				return archiveDescriptorFactory.buildArchiveDescriptor( file.toURI().toURL() );
			}
		}
		catch (MalformedURLException e) {
			throw new ArchiveException( "Unable to convert jar File to URL [" + jarFileReference + "]", e );
		}

		return null;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Relocate the archive to a simple ASCII path without spaces or special characters.
2. Reproduce the conversion standalone (file.toURI().toURL()) to confirm the environment issue.
3. Remove or fix conflicting URLStreamHandlerFactory setups installed by the application or container.

try {
    new File(jarFileReference).toURI().toURL();
} catch (MalformedURLException e) {
    throw new IllegalStateException("Jar path cannot be converted to URL: " + jarFileReference, e);
}

Catch org.hibernate.boot.archive.spi.ArchiveException during archive descriptor construction; on 'Unable to convert jar File to URL', test the conversion standalone and fix the path/handler environment.

When it happens

Trigger: An existing jar path that fails File -> URI -> URL conversion during archive descriptor construction (invalid URI characters in the path, custom/conflicting URL stream handlers).

Common situations: Deployment paths containing special characters; containers installing custom URL handlers; JDK or locale differences between environments producing different URI encoding behavior.

Related errors

• Unable to determine JAR Url from <url>. Cause: <cause>
• Could not access specified jar-file: <jarFileReference>
• Unable to extract bytes from InputStream
• Unable to access stream from jar file [%s] for entry [%s]
• Error accessing jar file [<rootFilePath>]

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