{"record":{"id":"3a36bbc6b5ef369b","repo":"hibernate/hibernate-orm","slug":"unable-to-determine-jar-url-from-url-cause-ca","errorCode":null,"errorMessage":"Unable to determine JAR Url from <url>. Cause: <cause>","messagePattern":"Unable to determine JAR Url from <url>\\. Cause: <cause>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java","lineNumber":120,"sourceCode":"\t\t\t\t\tjarUrl = new File(file).toURL();\n\t\t\t\t}\n\t\t\t}\n\t\t\telse {\n\t\t\t\ttry {\n\t\t\t\t\t//We reconstruct the URL probably to make it work in some specific environments\n\t\t\t\t\t//Forgot the exact details, sorry (and the Git history does not help)\n\t\t\t\t\tjarUrl = new URL( protocol, url.getHost(), url.getPort(), file );\n\t\t\t\t}\n\t\t\t\t//HHH-6442: Arquilian\n\t\t\t\tcatch ( final MalformedURLException e ) {\n\t\t\t\t\t//Just use the provided URL as-is, likely it has a URLStreamHandler\n\t\t\t\t\t//associated w/ the instance\n\t\t\t\t\tjarUrl = url;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tcatch (MalformedURLException e) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Unable to determine JAR Url from \" + url + \". Cause: \" + e.getMessage()\n\t\t\t);\n\t\t}\n\t\tBOOT_LOGGER.jarUrlFromUrlEntry( String.valueOf(url), String.valueOf(jarUrl) );\n\t\treturn jarUrl;\n\t}\n\n\n\t/// Attempt to resolve a `<jar-file/>` reference using a [ClassLoader].\n\t/// This form should only be used when we are parsing the `persistence.xml` ourselves\n\t/// and do not have an [ArchiveDescriptor].\n\t///\n\t/// @see org.hibernate.jpa.boot.internal.ParsedPersistenceXmlDescriptor\n\tpublic static URL resolveJarFileReference(String jarFileReference, URLClassLoader urlClassLoader) {\n\t\tassert jarFileReference != null;\n\t\tif ( jarFileReference.startsWith( \"file://\" ) ) {\n\t\t\tfinal var trimmed = jarFileReference.substring( \"file://\".length() );\n\t\t\treturn asFileReference( jarFileReference, trimmed );","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java#L102-L138","documentation":"ArchiveHelper.getJarURLFromURLEntry reconstructs the containing JAR's URL from the URL of a resource inside that jar (used during class/mapping scanning). When the entry URL's protocol, host, or file part cannot be reassembled into a well-formed URL, the MalformedURLException is wrapped in IllegalArgumentException. This almost always involves non-standard URL protocols or stream handlers supplied by application servers and containers.","triggerScenarios":"Hibernate scans an annotated-classes archive whose entry URL uses a container protocol (vfs:, zip:, wsjar:, bundle:) or has a file part that breaks URL construction, so new URL(protocol, host, port, file) throws MalformedURLException.","commonSituations":"JBoss/WildFly VFS deployments, WebSphere wsjar URLs, WebLogic zip URLs, OSGi bundles; nested/uber-jars scanned by Hibernate's archive code; deployment paths with characters that need escaping.","solutions":["Upgrade Hibernate — archive/URL handling in ArchiveHelper has been fixed repeatedly across releases.","Bypass URL inference entirely: list entity classes explicitly (addAnnotatedClass or <class> entries in persistence.xml) so no jar-entry URL must be derived.","In containers, let the app server's JPA integration drive archive discovery instead of building MetadataSources manually.","Normalize the deployment path (remove spaces and unusual characters)."],"exampleFix":"// before: rely on automatic jar scanning over container URLs\nMetadataSources sources = new MetadataSources(registry);\nsources.addPackage(\"com.acme.model\");\n\n// after: enumerate classes explicitly, no jar URL inference needed\nMetadataSources sources = new MetadataSources(registry);\nsources.addAnnotatedClass(com.acme.model.Customer.class);\nsources.addAnnotatedClass(com.acme.model.Order.class);","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    sources.addPackage(\"com.acme.model\"); // triggers archive scanning\n} catch (IllegalArgumentException e) {\n    if (String.valueOf(e.getMessage()).startsWith(\"Unable to determine JAR Url\")) {\n        // fallback: no jar-URL inference, register classes explicitly\n        sources.addAnnotatedClass(com.acme.model.Customer.class);\n        sources.addAnnotatedClass(com.acme.model.Order.class);\n    } else { throw e; }\n}","preventionTips":["In containers with custom URL protocols, list annotated classes explicitly instead of scanning.","Keep Hibernate up to date — archive URL handling improves each release.","Prefer deployment paths without spaces or special characters."],"tags":["hibernate","deployment","classpath","url","archive-scanning","app-server"],"backgroundTag":"jar-url-resolution-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}