hibernate/hibernate-orm · error · IllegalArgumentException

Unable to visit JAR {}. Cause: {}

Error message

Unable to visit JAR {}. Cause: {}

What it means

StandardArchiveDescriptorFactory.extractLocalFilePath converts an archive URL to a local file path: if the URL's file part contains no space it is normalized through URL.toURI(), which throws URISyntaxException for unencoded characters that are illegal in URIs ({, }, |, ^, backtick, and similar); the failure is rethrown as this IllegalArgumentException. Note the deliberate quirk that a file part containing a space is assumed to be already unescaped by the container and returned raw.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/StandardArchiveDescriptorFactory.java:65

		}

		//let's assume the url can return the jar as a zip stream
		return new JarInputStreamBasedArchiveDescriptor( this, url, entry );

	}

	protected String extractLocalFilePath(URL url) {
		final String filePart = url.getFile();
		if ( filePart != null && filePart.indexOf( ' ' ) != -1 ) {
			//unescaped (from the container), keep as is
			return filePart;
		}
		else {
			try {
				return url.toURI().getSchemeSpecificPart();
			}
			catch (URISyntaxException e) {
				throw new IllegalArgumentException(
						"Unable to visit JAR " + url + ". Cause: " + e.getMessage(), e
				);
			}
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Move the deployment to a path containing only URI-safe characters
2. Construct the URL via URI/File (new File(p).toURI().toURL()) so it is encoded, instead of new URL(rawString)
3. URL-encode the illegal characters in the path before passing it to Hibernate

Example fix

// before
URL url = new URL("file:///opt/{env}/app.war"); // braces are URI-illegal -> toURI() throws

// after
URL url = new File("/opt/{env}/app.war").toURI().toURL(); // encoded, toURI() succeeds

// replicate Hibernate's own heuristic and reject URLs it cannot normalize
static void assertUriSafe(URL archiveUrl) {
    final String filePart = archiveUrl.getFile();
    if (filePart == null || filePart.indexOf(' ') != -1) return; // treated as raw by Hibernate
    try { archiveUrl.toURI(); }
    catch (URISyntaxException e) {
        throw new IllegalArgumentException("Archive URL needs encoding: " + archiveUrl, e);
    }
}

try {
    ArchiveDescriptor d = archiveDescriptorFactory.buildArchiveDescriptor(url, true);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unable to visit JAR")) {
        throw new IllegalStateException("Archive path contains URI-illegal characters; encode or rename it", e);
    }
    throw e;
}

When it happens

Trigger: Archive scanning with a URL whose file part contains unencoded URI-illegal characters other than a plain space — e.g. '/opt/{env}/app.war', a path containing '|' or backslashes, or unencoded non-ASCII characters from a non-English locale.

Common situations: Temp/deploy directories templated with brace placeholders; misconfigured container valves producing raw paths; URLs assembled by string concatenation instead of URI-based construction.

Related errors

• Unable to determine JAR Url from <url>. Cause: <cause>
• Unable to convert jar File to URL [<jarFileReference>]
• Could not access specified jar-file: <jarFileReference>
• Unable to extract bytes from InputStream
• 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/a985e9b5c828b461. Report an issue: GitHub.