hibernate/hibernate-orm · error · ArchiveException

Unable to resolve <jar-file/> reference - <jarFileReference>

Error message

Unable to resolve <jar-file/> reference - <jarFileReference>

What it means

Thrown by ExplodedArchiveDescriptor when a <jar-file/> reference from persistence.xml cannot be resolved to an existing file relative to the exploded archive root.

Source

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

			}
		}

		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. Verify the jar file exists at the path referenced by <jar-file> relative to the persistence unit root.
2. Correct the relative path in the <jar-file> element of persistence.xml.
3. Rebuild/redeploy the exploded archive so all referenced jars are present.

Example fix

Verify the <jar-file/> reference in persistence.xml: the jar must exist, be readable, and be resolvable relative to the persistence unit root. Fix the path or add the jar to the classpath/deployment.

When it happens

Trigger: persistence.xml lists a <jar-file> that does not exist at the expected location relative to the persistence unit root directory.

Common situations: A jar was renamed, moved, or not copied into the exploded deployment; the relative path in <jar-file> is wrong (extra '../' or missing subdirectory).

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