hibernate/hibernate-orm · error · ArchiveException

Unable to create archive entry URI: %s - %s

Error message

Unable to create archive entry URI: %s - %s

What it means

While visiting the entries of a nested jar (a URL of the form jar:...!/...), Hibernate synthesizes each entry's URI as archiveUrl + "!/" + entryName and passes it to java.net.URI. If that concatenated string contains characters that are illegal in a URI, the URISyntaxException is caught and rethrown as this ArchiveException naming the archive URL and the offending entry name. It is purely an encoding defect in the archive's URL or entry names, not a data problem.

Source

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

				if ( !jarEntryName.endsWith( ".class" ) ) {
					continue;
				}

				if ( jarEntry.isDirectory() ) {
					continue;
				}

				try {
					entryConsumer.accept( new ArchiveEntryImpl(
							jarEntryName,
							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() );

View on GitHub (pinned to fad1729dce)

Solutions

1. Move or rename the deployment path so the archive URL contains no characters illegal in URIs
2. Hand Hibernate a properly encoded archive URL (build it via File.toURI().toURL())
3. Exclude the problematic nested archive from entity scanning or reference it as a top-level archive
4. Upgrade Hibernate — archive-entry URI construction has received encoding fixes across releases

// fail fast if the archive URL is not URI-safe before Hibernate builds entry URIs
static void assertScannableUrl(URL archiveUrl) {
    try { new URI(archiveUrl.toString()); }
    catch (URISyntaxException e) {
        throw new IllegalArgumentException("Archive URL is not URI-safe: " + archiveUrl, e);
    }
}

try {
    sessionFactory = new Configuration().buildSessionFactory();
} catch (ArchiveException e) {
    if (e.getMessage().startsWith("Unable to create archive entry URI")) {
        // encoding problem in the archive URL / entry names — report path, not stack trace
        throw new IllegalStateException("Unencoded characters in archive URL; re-encode deployment path", e);
    }
    throw e;
}

When it happens

Trigger: Archive scanning of a nested jar whose URL string contains unencoded characters illegal in URIs — spaces, {, }, |, ^, backtick, or unencoded non-ASCII — for example a deployment path with spaces/braces, or a container handing out a raw unencoded URL that gets concatenated with the entry name.

Common situations: Deploying under paths containing spaces (e.g. 'C:\Program Files\...') or brace/pipe characters; app-server or OSGi protocols returning unencoded URLs; moving an app from a dev box to a container whose layout introduces odd characters.

Related errors

• Error accessing nested jar archive [{}]
• 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/87c2c92b082ff33c. Report an issue: GitHub.