{"record":{"id":"a985e9b5c828b461","repo":"hibernate/hibernate-orm","slug":"unable-to-visit-jar-cause","errorCode":null,"errorMessage":"Unable to visit JAR {}. Cause: {}","messagePattern":"Unable to visit JAR (.+?)\\. Cause: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/StandardArchiveDescriptorFactory.java","lineNumber":65,"sourceCode":"\t\t}\n\n\t\t//let's assume the url can return the jar as a zip stream\n\t\treturn new JarInputStreamBasedArchiveDescriptor( this, url, entry );\n\n\t}\n\n\tprotected String extractLocalFilePath(URL url) {\n\t\tfinal String filePart = url.getFile();\n\t\tif ( filePart != null && filePart.indexOf( ' ' ) != -1 ) {\n\t\t\t//unescaped (from the container), keep as is\n\t\t\treturn filePart;\n\t\t}\n\t\telse {\n\t\t\ttry {\n\t\t\t\treturn url.toURI().getSchemeSpecificPart();\n\t\t\t}\n\t\t\tcatch (URISyntaxException e) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"Unable to visit JAR \" + url + \". Cause: \" + e.getMessage(), e\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n}\n","sourceCodeStart":47,"sourceCodeEnd":72,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/StandardArchiveDescriptorFactory.java#L47-L72","documentation":"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.","triggerScenarios":"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.","commonSituations":"Temp/deploy directories templated with brace placeholders; misconfigured container valves producing raw paths; URLs assembled by string concatenation instead of URI-based construction.","solutions":["Move the deployment to a path containing only URI-safe characters","Construct the URL via URI/File (new File(p).toURI().toURL()) so it is encoded, instead of new URL(rawString)","URL-encode the illegal characters in the path before passing it to Hibernate"],"exampleFix":"// before\nURL url = new URL(\"file:///opt/{env}/app.war\"); // braces are URI-illegal -> toURI() throws\n\n// after\nURL url = new File(\"/opt/{env}/app.war\").toURI().toURL(); // encoded, toURI() succeeds","handlingStrategy":"validation","validationCode":"// replicate Hibernate's own heuristic and reject URLs it cannot normalize\nstatic void assertUriSafe(URL archiveUrl) {\n    final String filePart = archiveUrl.getFile();\n    if (filePart == null || filePart.indexOf(' ') != -1) return; // treated as raw by Hibernate\n    try { archiveUrl.toURI(); }\n    catch (URISyntaxException e) {\n        throw new IllegalArgumentException(\"Archive URL needs encoding: \" + archiveUrl, e);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    ArchiveDescriptor d = archiveDescriptorFactory.buildArchiveDescriptor(url, true);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Unable to visit JAR\")) {\n        throw new IllegalStateException(\"Archive path contains URI-illegal characters; encode or rename it\", e);\n    }\n    throw e;\n}","preventionTips":["Construct URLs from File/URI, never by string concatenation","Avoid braces, pipes, backticks and non-ASCII characters in deployment paths"],"tags":["hibernate","url","uri-encoding","archive-scanning","filesystem-path"],"backgroundTag":"malformed-uri","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}