hibernate/hibernate-orm · error · ArchiveException

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

Error message

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

What it means

Thrown during Hibernate bootstrap while it resolves <jar-file/> elements from persistence.xml. Hibernate first tries to interpret the reference as a relative URL, then falls back to ArchiveHelper.standardJarFileReferenceResolution (URL or file-path interpretation); if neither yields an archive, this ArchiveException is thrown with the unresolved reference. It means Hibernate has no way to open the listed managed-class jar at all.

Source

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

	@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. Correct the <jar-file/> value to an absolute file path or valid URL that exists at runtime
2. Drop <jar-file/> and list entity classes explicitly with <class> elements instead
3. With Spring Boot, avoid <jar-file/> entirely and let Spring's entity scanning register the entities
4. Verify the referenced jar is actually deployed alongside the persistence unit

Example fix

// before (persistence.xml)
<persistence-unit name="pu">
    <jar-file>entities.jar</jar-file> <!-- relative, not resolvable from the PU root -->
</persistence-unit>

// after
<persistence-unit name="pu">
    <jar-file>file:///opt/app/lib/entities.jar</jar-file> <!-- absolute URL that exists -->
</persistence-unit>

// verify every <jar-file/> entry before building the EntityManagerFactory
static boolean jarReferenceResolvable(String ref) {
    if (new File(ref).isFile()) return true;
    try { new URL(ref); return true; }
    catch (MalformedURLException e) { return false; }
}
// usage:
for (String ref : persistenceUnitJarFileEntries()) {
    if (!jarReferenceResolvable(ref))
        throw new IllegalArgumentException("Unresolvable <jar-file/> entry: " + ref);
}

try {
    EntityManagerFactory emf = Persistence.createEntityManagerFactory("pu");
} catch (ArchiveException e) {
    // message ends with the unresolved reference; surface it in the bootstrap error report
    throw new IllegalStateException("Bad <jar-file/> in persistence.xml: " + e.getMessage(), e);
}

When it happens

Trigger: Building a SessionFactory/EntityManagerFactory from a persistence.xml whose <jar-file> value is neither a parseable URL nor an existing file-system path — e.g. <jar-file>libs/entities.jar</jar-file> when the file is not at that location relative to the persistence unit root, or a classpath:-style reference that Hibernate does not expand.

Common situations: Running inside Spring Boot fat/executable jars where jar-inside-jar references cannot be resolved; containers that unpack deployments differently than the dev environment; typos in the jar-file path; referencing a jar that is simply not deployed.

Related errors

• Could not resolve jar-file: <jarFileReference>
• Unable to instantiate configured ArchiveDescriptorFactory -
• Schema generation configuration indicated to include CREATE
• The {storageEngine} storage engine is not supported
• The specified package name cannot be null

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