What causes "Could not resolve jar-file: " in hibernate/hibernate-orm?

Reference the jar by an absolute path or file: URL that is valid on the target machine.

hibernate/hibernate-orm · error · HibernateException

Could not resolve jar-file: <jarFileReference>

Error message

Could not resolve jar-file: <jarFileReference>

What it means

When Hibernate resolves a <jar-file> reference, ArchiveHelper.resolveJarFileReference tries the string first as a file path/URL (tryAsFileReference) and then as a classloader-relative resource. If neither works it throws HibernateException 'Could not resolve jar-file' — the referenced jar cannot be found by any available mechanism.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java:154

		if ( jarFileReference.startsWith( "file://" ) ) {
			final var trimmed = jarFileReference.substring( "file://".length() );
			return asFileReference( jarFileReference, trimmed );
		}
		else {
			// try it as a File reference
			var asFileReference = tryAsFileReference( jarFileReference, jarFileReference );
			if ( asFileReference != null ) {
				return asFileReference;
			}

			// try it as a path relative to the container
			final URL relativeReference = urlClassLoader.getResource( jarFileReference );
			if ( relativeReference != null ) {
				return relativeReference;
			}
		}

		throw new HibernateException( "Could not resolve jar-file: " + jarFileReference );
	}

	private static URL tryAsFileReference(String jarFileReference, String trimmed) {
		final File jarFile = new File( trimmed );
		try {
			if ( jarFile.exists() ) {
				return jarFile.toURI().toURL();
			}
		}
		catch (MalformedURLException ignore) {
		}
		return null;
	}


	public static URL asFileReference(String jarFileReference, String trimmed) {
		final File jarFile = new File( trimmed );
		if ( !jarFile.exists() ) {

View on GitHub (pinned to fad1729dce)

Solutions

Reference the jar by an absolute path or file: URL that is valid on the target machine.
Put the jar on the classpath and reference it relative to the classpath root.
Prefer explicit <class> entries or annotation scanning over <jar-file> to avoid path resolution entirely.

Defensive patterns

Strategy: validation

Validate before calling

static boolean jarFileResolvable(String ref, ClassLoader cl) {
    return new File(ref).exists() || cl.getResource(ref) != null;
}

Try / catch

Catch org.hibernate.HibernateException during archive resolution, match 'Could not resolve jar-file', and report the reference plus the deployment's absolute root path.

Prevention

Validate <jar-file> entries against the actual deployment layout for each environment.
Prefer absolute paths or classpath-relative references.
Consider replacing <jar-file> with explicit <class> entries.

When it happens

Trigger: A persistence.xml <jar-file>lib/my-entities.jar</jar-file> entry whose path matches neither an existing file on disk nor a classloader-visible resource: misspelled name, wrong relative base, or the jar never shipped.

Common situations: Moving a persistence unit from an EE server (where jar-file resolves relative to the deployment) to Java SE; builds that never package the entities jar; relative paths that break in Docker or different working directories.

Related errors

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