hibernate/hibernate-orm · error · ArchiveException

Unable to convert relative <jar-file/> reference to URL [<ja

Error message

Unable to convert relative <jar-file/> reference to URL [<jarFileReference>]

What it means

Thrown by ExplodedArchiveDescriptor when a relative <jar-file/> reference in persistence.xml cannot be converted to a URL because the base URL of the exploded archive is malformed (MalformedURLException).

Source

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

		final File localFile = new File( rootDirectory, relativePath );
		if ( !localFile.exists() ) {
			return null;
		}

		return localFile;
	}

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

		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 );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use an absolute URL or a properly escaped path for the persistence unit root.
2. Remove spaces and special characters from the deployment directory path.
3. Reference the jar file with an absolute path in <jar-file> instead of a relative one.

Example fix

Provide a valid relative path for the <jar-file/> entry in persistence.xml and make sure the file actually exists relative to the persistence unit root. If the path contains spaces or special characters, URL-encode them correctly.

When it happens

Trigger: persistence.xml contains a relative <jar-file> entry and the persistence unit root is an exploded directory whose URL cannot be constructed.

Common situations: Running from an exploded deployment with a root path containing characters invalid in URLs, or a misconfigured persistence-unit root.

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