hibernate/hibernate-orm · error · HibernateException

Could not access specified jar-file: <jarFileReference>

Error message

Could not access specified jar-file: <jarFileReference>

What it means

After confirming the jar file exists, asFileReference converts File -> URI -> URL; if that throws MalformedURLException, Hibernate wraps it as HibernateException 'Could not access specified jar-file'. This is a rare environment-level failure — a filesystem path that cannot be expressed as a valid URL by the current JVM — not a mapping problem.

Source

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

				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 {
		try {
			return getBytesFromInputStream( inputStream );
		}
		catch (IOException e) {
			throw new ArchiveException( "Unable to extract bytes from InputStream", e );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Move or rename the jar to a plain ASCII path without special characters.
2. Reproduce standalone with new File(path).toURI().toURL() to confirm it is environmental.
3. Check container/JDK URL stream handler configuration if the path itself is plain.

try {
    new File(jarPath).toURI().toURL();
} catch (MalformedURLException e) {
    throw new IllegalStateException("Jar path cannot be converted to URL: " + jarPath, e);
}

Catch org.hibernate.HibernateException during archive setup; on 'Could not access specified jar-file', reproduce File.toURI().toURL() standalone to confirm the environment issue.

When it happens

Trigger: An existing file whose path fails File.toURI().toURL() during jar reference conversion: path components that break URI construction or misbehaving protocol handlers.

Common situations: Deployments under paths with non-ASCII or special characters; locale/encoding mismatches between machines; exotic filesystems reported by the OS.

Related errors

• Unable to convert jar File to URL [<jarFileReference>]
• Unable to determine JAR Url from <url>. Cause: <cause>
• Could not resolve jar-file: <jarFileReference>
• Could not find specified jar-file: <jarFileReference>
• Unable to extract bytes from InputStream

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