hibernate/hibernate-orm · error · ArchiveException

Error accessing nested jar archive [{}]

Error message

Error accessing nested jar archive [{}]

What it means

Thrown when opening or reading a nested jar archive fails with an IOException during visitEntries: either archiveUrl.openStream() cannot supply a stream (the protocol handler cannot open the connection, or the resource is gone), or the JarInputStream read fails (corrupt or truncated archive). The original IOException is attached as the cause.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/NestedJarDescriptor.java:80

							jarEntryName,
							new URI( archiveUrl + "!/" + jarEntryName ),
							buildByteBasedInputStreamAccess( jarEntryName, jarInputStream )
					) );
				}
				catch (URISyntaxException e) {
					throw new ArchiveException(
							String.format( Locale.ROOT,
									"Unable to create archive entry URI: %s - %s",
									archiveUrl,
									jarEntry.getName()
							),
							e
					);
				}
			}
		}
		catch (IOException e) {
			throw new ArchiveException( "Error accessing nested jar archive [" + archiveUrl + "]", e );
		}
	}

	@Override
	public @Nullable ArchiveEntry findEntry(String relativePath) {
		try (final InputStream is = new BufferedInputStream( archiveUrl.openStream() );
			final JarInputStream jarInputStream = new JarInputStream( is )) {
			JarEntry jarEntry;
			while ( ( jarEntry = jarInputStream.getNextJarEntry() ) != null ) {
				final String jarEntryName = jarEntry.getName();
				if ( relativePath.equals( jarEntryName ) ) {
					try {
						return new ArchiveEntryImpl(
								jarEntryName,
								jarEntryName,
								new URI( archiveUrl + "!/" + jarEntryName ),
								buildByteBasedInputStreamAccess( jarEntryName, jarInputStream )
						);

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify the jar exists and can be opened at scan time (open it yourself once before bootstrap)
2. Copy the archive to a stable local file location and point Hibernate at that copy
3. Stop the old SessionFactory before replacing/redeploying jars; avoid scanning during redeploy
4. For exotic URL protocols, register a URLStreamHandlerFactory or use file-based archives

// prove the archive is openable and looks like a jar before bootstrap
static void assertReadableJar(URL url) throws IOException {
    try (InputStream in = new BufferedInputStream(url.openStream());
         JarInputStream jar = new JarInputStream(in)) {
        if (jar.getNextJarEntry() == null && jar.getManifest() == null)
            throw new IOException("Not a readable jar: " + url);
    }
}

try {
    metadata.scanEnvironment().getExplicitFileReferences()...; // or SessionFactory build
} catch (ArchiveException e) {
    if (e.getCause() instanceof IOException io) {
        // distinguish deleted/locked file vs corrupt jar via io.getMessage()
        throw new IllegalStateException("Archive unreadable during scan: " + io.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: visitEntries() on a NestedJarDescriptor whose archive URL points to a jar that was deleted or replaced between discovery and scan; a corrupt/truncated jar; a URL protocol (bundle://, vfs://, custom scheme) whose stream cannot be opened; file permissions denying read access.

Common situations: Hot redeploy while another thread is still scanning; partially copied jars in temp/repo directories; OSGi or app-server protocols without usable stream handlers; locked files on Windows during redeploy.

Related errors

• Unable to create archive entry URI: %s - %s
• Unable to determine JAR Url from <url>. Cause: <cause>
• Unable to extract bytes from InputStream
• Unable to convert jar File to URL [<jarFileReference>]
• Unable to access stream from jar file [%s] for entry [%s]

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