What causes "Error accessing jar file [ ]" in hibernate/hibernate-orm?

Read the chained cause and fix the underlying I/O problem (permissions, missing file, lock).

hibernate/hibernate-orm · error · ArchiveException

Error accessing jar file [<rootFilePath>]

Error message

Error accessing jar file [<rootFilePath>]

What it means

ExplodedArchiveDescriptor.visitArchive wraps any IOException raised while scanning the root file (opening it as a jar, iterating entries, building entry URIs) as ArchiveException 'Error accessing jar file'. Unlike its sibling message, the IOException is attached as the cause — always inspect getCause() for the real reason.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java:171

							String.format(
									"Unable to access stream from jar file [%s] for entry [%s]",
									jarFile.getName(),
									zipEntry.getName()
							)
					);
				}

				// todo (jpa4) : for now, pass null
				entryConsumer.accept( new ArchiveEntryImpl(
						name,
						relativeName,
						new URL( "jar:" + entryUriBase + "!/" + relativeName ).toURI(),
						inputStreamAccess
				) );
			}
		}
		catch (IOException e) {
			throw new ArchiveException( "Error accessing jar file [" + rootFile.getAbsolutePath() + "]", e );
		}
		catch (URISyntaxException e) {
			throw new ArchiveException( "Unable to create archive entry URI", e );
		}
	}


	@Override
	public @Nullable ArchiveEntry findEntry(String relativePath) {
		final File file = resolveRelativePath( relativePath );
		if ( file == null ) {
			return null;
		}
		final String name = file.getAbsolutePath();
		final InputStreamAccess inputStreamAccess = new FileInputStreamAccess( name, file );
		return new ArchiveEntryImpl( name, relativePath, file.toURI(), inputStreamAccess );
	}

View on GitHub (pinned to fad1729dce)

Solutions

Read the chained cause and fix the underlying I/O problem (permissions, missing file, lock).
Correct the scan configuration so jar paths are handled by the jar archive descriptor and directories by the exploded one.
Grant the server user read access to the whole deployment tree and avoid mutating it during startup.

Defensive patterns

Strategy: try-catch

Try / catch

Catch org.hibernate.boot.archive.spi.ArchiveException around bootstrap and always inspect getCause() — the chained IOException holds the real reason (permission denied, file missing, lock). Fix the underlying access problem; no retry helps until it is resolved.

Prevention

Match scan configuration to the artifact type: directories as exploded, jars as jar archives.
Grant read access to the full deployment tree for the server user.
Do not delete or rewrite deployed files while the application boots.

When it happens

Trigger: The root path handed to the exploded-archive descriptor actually names a jar file, and reading it throws IOException: missing permissions, file removed or locked during the scan, or a truncated archive.

Common situations: A jar path configured where an exploded directory was expected (archive-type mismatch in the scan setup); exploded WARs containing jars scanned during hot redeploys; permission-restricted containers.

Related errors

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