{"record":{"id":"bce0061e9b11dc83","repo":"hibernate/hibernate-orm","slug":"unable-to-convert-jar-file-to-url-jarfilereferen","errorCode":null,"errorMessage":"Unable to convert jar File to URL [<jarFileReference>]","messagePattern":"Unable to convert jar File to URL \\[<jarFileReference>\\]","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java","lineNumber":263,"sourceCode":"\tpublic static ArchiveDescriptor standardJarFileReferenceResolution(\n\t\t\t@Nonnull String jarFileReference,\n\t\t\tArchiveDescriptorFactory archiveDescriptorFactory) {\n\n\t\t// try it as a URL\n\t\tfinal var asUrl = resolveJarFileReferenceAsUrl( jarFileReference, archiveDescriptorFactory );\n\t\tif ( asUrl != null ) {\n\t\t\treturn asUrl;\n\t\t}\n\n\t\t// try it as a File path\n\t\ttry {\n\t\t\tvar file = new File( 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\n\t\treturn null;\n\t}\n}\n","sourceCodeStart":245,"sourceCodeEnd":269,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java#L245-L269","documentation":"While building an ArchiveDescriptor from a jar reference, ArchiveHelper finds the file on disk but File.toURI().toURL() throws MalformedURLException, which is wrapped as ArchiveException 'Unable to convert jar File to URL'. Rare and environmental: the path exists yet cannot be turned into a well-formed URL by this JVM.","triggerScenarios":"An existing jar path that fails File -> URI -> URL conversion during archive descriptor construction (invalid URI characters in the path, custom/conflicting URL stream handlers).","commonSituations":"Deployment paths containing special characters; containers installing custom URL handlers; JDK or locale differences between environments producing different URI encoding behavior.","solutions":["Relocate the archive to a simple ASCII path without spaces or special characters.","Reproduce the conversion standalone (file.toURI().toURL()) to confirm the environment issue.","Remove or fix conflicting URLStreamHandlerFactory setups installed by the application or container."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"try {\n    new File(jarFileReference).toURI().toURL();\n} catch (MalformedURLException e) {\n    throw new IllegalStateException(\"Jar path cannot be converted to URL: \" + jarFileReference, e);\n}","typeGuard":null,"tryCatchPattern":"Catch org.hibernate.boot.archive.spi.ArchiveException during archive descriptor construction; on 'Unable to convert jar File to URL', test the conversion standalone and fix the path/handler environment.","preventionTips":["Keep archive paths simple (ASCII, no special characters).","Audit custom URLStreamHandlerFactory installations in the app or container."],"tags":["hibernate","archive-scanning","url","deployment","environment"],"backgroundTag":"jar-url-resolution-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}