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

Verify the location with Files.exists and correct the reference to the real jar path.

hibernate/hibernate-orm · error · HibernateException

Could not find specified jar-file: <jarFileReference>

Error message

Could not find specified jar-file: <jarFileReference>

What it means

ArchiveHelper.asFileReference converts a jar-file reference into a file-based URL and requires File.exists(); when the named file is absent it throws HibernateException 'Could not find specified jar-file'. Unlike the resolveJarFileReference path there is no classloader fallback here — the reference is treated strictly as a filesystem location.

Source

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

	}

	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() ) {
			throw new HibernateException( "Could not find specified jar-file: " + jarFileReference );
		}
		try {
			return jarFile.toURI().toURL();
		}
		catch (MalformedURLException e) {
			throw new HibernateException( "Could not access specified jar-file: " + jarFileReference, e );
		}
	}

	/// Extracts the bytes out of an InputStream.  This form is the same as [#getBytesFromInputStream]
	/// except that any [IOException] is wrapped as (runtime) [ArchiveException]
	///
	/// @param inputStream The stream from which to extract bytes.
	///
	/// @return The bytes
	///
	/// @throws ArchiveException Indicates a problem accessing the stream
	public static byte[] getBytesFromInputStreamSafely(InputStream inputStream) throws ArchiveException {

View on GitHub (pinned to fad1729dce)

Solutions

Verify the location with Files.exists and correct the reference to the real jar path.
Rebuild/redeploy the artifact so the jar is present where the reference expects it.
Use absolute paths or classpath-relative references instead of environment-dependent relative ones.

Defensive patterns

Strategy: validation

Validate before calling

Path p = Paths.get(jarFileReference);
if (!Files.exists(p)) {
    throw new IllegalStateException("Configured jar-file does not exist: " + p.toAbsolutePath());
}

Try / catch

Catch org.hibernate.HibernateException around archive setup; on 'Could not find specified jar-file', log the absolute expected path and the current working directory to pinpoint the mismatch.

Prevention

Check Files.exists for configured jar paths at startup with a clear error message.
Avoid environment-dependent relative paths in deployment descriptors.

When it happens

Trigger: A jar-file reference that reaches asFileReference but points to a file that does not exist at startup time: deleted artifact, wrong working directory, or a path valid only in another environment.

Common situations: Paths hardcoded for one machine; build outputs renamed between environments; cleanup scripts or hot redeploys removing jars before Hibernate starts.

Related errors

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