{"record":{"id":"9e74731a1756a71a","repo":"hibernate/hibernate-orm","slug":"unable-to-convert-relative-jar-file-reference-to-u","errorCode":null,"errorMessage":"Unable to convert relative jar-file reference to URL [{}]","messagePattern":"Unable to convert relative jar-file reference to URL \\[(.+?)\\]","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarFileBasedArchiveDescriptor.java","lineNumber":208,"sourceCode":"\t\tfinally {\n\t\t\ttry {\n\t\t\t\tjarFile.close();\n\t\t\t}\n\t\t\tcatch ( Exception ignore ) {\n\t\t\t}\n\t\t}\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 new NestedJarDescriptor( 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\tthrow new ArchiveException( \"Unable to resolve <jar-file/> reference - \" + jarFileReference );\n\t}\n}\n","sourceCodeStart":190,"sourceCodeEnd":220,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarFileBasedArchiveDescriptor.java#L190-L220","documentation":"Thrown by JarFileBasedArchiveDescriptor when a relative jar-file reference cannot be converted to a URL because the base jar URL is malformed (MalformedURLException).","triggerScenarios":"persistence.xml contains a relative <jar-file> and the URL of the containing jar cannot be constructed, usually due to invalid characters in the jar's path.","commonSituations":"Application deployed in a directory whose path contains spaces or characters not valid in URLs.","solutions":["Move the application to a path without spaces or special characters.","Use an absolute, properly escaped file: URL for the jar-file reference."],"exampleFix":"Fix the relative jar-file reference so it resolves to a real file from the archive root. URL-encode special characters in the path, or switch to an absolute file path.","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"}