{"record":{"id":"c0ee2b6868c5d180","repo":"hibernate/hibernate-orm","slug":"unable-to-convert-relative-jar-file-reference-t","errorCode":null,"errorMessage":"Unable to convert relative <jar-file/> reference to URL [<jarFileReference>]","messagePattern":"Unable to convert relative <jar-file/> reference to URL \\[<jarFileReference>\\]","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java","lineNumber":213,"sourceCode":"\n\t\tfinal File localFile = new File( rootDirectory, relativePath );\n\t\tif ( !localFile.exists() ) {\n\t\t\treturn null;\n\t\t}\n\n\t\treturn localFile;\n\t}\n\n\t@Override @Nonnull\n\tpublic ArchiveDescriptor resolveJarFileReference(@Nonnull String jarFileReference) {\n\t\t// try it as a relative reference\n\t\tfinal ArchiveEntry entry = findEntry( jarFileReference );\n\t\tif ( entry != null ) {\n\t\t\ttry {\n\t\t\t\treturn archiveDescriptorFactory.buildArchiveDescriptor( entry.getUri().toURL() );\n\t\t\t}\n\t\t\tcatch (MalformedURLException e) {\n\t\t\t\tthrow new ArchiveException( \"Unable to convert relative <jar-file/> reference to URL [\" + jarFileReference + \"]\", e );\n\t\t\t}\n\t\t}\n\n\t\tvar standardResolution = ArchiveHelper.standardJarFileReferenceResolution( jarFileReference, archiveDescriptorFactory );\n\t\tif ( standardResolution != null ) {\n\t\t\treturn standardResolution;\n\t\t}\n\n\t\ttry {\n\t\t\tvar file = new File( resolveRootDirectory(), jarFileReference );\n\t\t\tif ( file.exists() ) {\n\t\t\t\treturn archiveDescriptorFactory.buildArchiveDescriptor( file.toURI().toURL() );\n\t\t\t}\n\t\t}\n\t\tcatch (MalformedURLException e) {\n\t\t\tthrow new ArchiveException( \"Unable to convert jar File to URL [\" + jarFileReference + \"]\", e );\n\t\t}\n","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java#L195-L231","documentation":"Thrown by ExplodedArchiveDescriptor when a relative <jar-file/> reference in persistence.xml cannot be converted to a URL because the base URL of the exploded archive is malformed (MalformedURLException).","triggerScenarios":"persistence.xml contains a relative <jar-file> entry and the persistence unit root is an exploded directory whose URL cannot be constructed.","commonSituations":"Running from an exploded deployment with a root path containing characters invalid in URLs, or a misconfigured persistence-unit root.","solutions":["Use an absolute URL or a properly escaped path for the persistence unit root.","Remove spaces and special characters from the deployment directory path.","Reference the jar file with an absolute path in <jar-file> instead of a relative one."],"exampleFix":"Provide a valid relative path for the <jar-file/> entry in persistence.xml and make sure the file actually exists relative to the persistence unit root. If the path contains spaces or special characters, URL-encode them correctly.","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}