hibernate/hibernate-orm · error · ArchiveException

Unable to resolve <jar-file/> reference - {}

Error message

Unable to resolve <jar-file/> reference - {}

What it means

Thrown by JarFileBasedArchiveDescriptor when the resolved file for a <jar-file/> reference does not exist relative to the containing jar's location.

Source

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

	@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. Ensure the referenced jar is packaged at the expected location.
2. Correct the relative path in the <jar-file> element.
3. List the deployment contents to confirm where the jar actually resides.

Example fix

The <jar-file/> reference could not be resolved. Check that the referenced jar exists relative to the persistence unit root and that the path in persistence.xml is spelled correctly.

When it happens

Trigger: The relative <jar-file> path in persistence.xml points to a jar that is missing from the deployment.

Common situations: Missing jar in the packaged application; incorrect relative path with wrong number of '../' segments.

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