hibernate/hibernate-orm · error · ArchiveException

Unable to convert relative jar-file reference to URL [{}]

Error message

Unable to convert relative jar-file reference to URL [{}]

What it means

Thrown by JarFileBasedArchiveDescriptor when a relative jar-file reference cannot be converted to a URL because the base jar URL is malformed (MalformedURLException).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarFileBasedArchiveDescriptor.java:208

		finally {
			try {
				jarFile.close();
			}
			catch ( Exception ignore ) {
			}
		}
	}

	@Override @Nonnull
	public ArchiveDescriptor resolveJarFileReference(@Nonnull String jarFileReference) {
		// try it as a relative reference
		final ArchiveEntry entry = findEntry( jarFileReference );
		if ( entry != null ) {
			try {
				return new NestedJarDescriptor( entry.getUri().toURL() );
			}
			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;
		}

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

View on GitHub (pinned to fad1729dce)

Solutions

1. Move the application to a path without spaces or special characters.
2. Use an absolute, properly escaped file: URL for the jar-file reference.

Example fix

Fix the relative jar-file reference so it resolves to a real file from the archive root. URL-encode special characters in the path, or switch to an absolute file path.

When it happens

Trigger: persistence.xml contains a relative <jar-file> and the URL of the containing jar cannot be constructed, usually due to invalid characters in the jar's path.

Common situations: Application deployed in a directory whose path contains spaces or characters not valid in URLs.

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