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

Error "Unable to convert relative jar-file reference to URL [{}]" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java:257

				jarInputStream.close();
			}
			catch (IOException e) {
				// Ignore
			}
		}
		return null;
	}

	@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. Fix the <jar-file/> reference in persistence.xml so it is a valid relative path or absolute URL; Hibernate resolves it relative to the persistence unit root.
2. Make sure the referenced jar actually exists relative to the root URL of the persistence unit.
3. If the jar lives outside the persistence unit root, use an absolute file: or jar: URL instead of a relative reference.

When it happens

Trigger: A relative <jar-file/> reference in persistence.xml cannot be converted to a URL.

Common situations: JSE-style persistence.xml using relative jar paths, or a pu root URL with a nonstandard protocol (e.g. inside a fat jar).

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