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

Thrown by ExplodedArchiveDescriptor when a resolved jar File for a <jar-file/> reference cannot be converted to a URL (MalformedURLException) while processing an exploded archive.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java:229

			}
			catch (MalformedURLException e) {
				throw new ArchiveException( "Unable to convert relative <jar-file/> reference to URL [" + jarFileReference + "]", e );
			}
		}

		var standardResolution = ArchiveHelper.standardJarFileReferenceResolution( jarFileReference, archiveDescriptorFactory );
		if ( standardResolution != null ) {
			return standardResolution;
		}

		try {
			var file = new File( resolveRootDirectory(), 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 );
		}

		throw new ArchiveException( "Unable to resolve <jar-file/> reference - " + jarFileReference );
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Relocate the application to a path containing only URL-safe characters.
2. Verify the referenced jar file actually exists at the resolved location.
3. Use a packaged JAR deployment instead of an exploded directory.

Example fix

Check that the jar file path referenced by the <jar-file/> element exists on disk and is readable. Convert the File to a URL with toURI().toURL() and catch MalformedURLException only around genuinely invalid paths.

When it happens

Trigger: The <jar-file> reference resolves to a File on disk, but File.toURI().toURL() fails because the path cannot form a valid URL.

Common situations: Exploded deployments located on paths with spaces, non-ASCII characters, or unusual mount points.

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