{"record":{"id":"80b9f1b0b83d7534","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-jar-file-jarfilereference","errorCode":null,"errorMessage":"Could not resolve jar-file: <jarFileReference>","messagePattern":"Could not resolve jar-file: <jarFileReference>","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java","lineNumber":154,"sourceCode":"\t\tif ( jarFileReference.startsWith( \"file://\" ) ) {\n\t\t\tfinal var trimmed = jarFileReference.substring( \"file://\".length() );\n\t\t\treturn asFileReference( jarFileReference, trimmed );\n\t\t}\n\t\telse {\n\t\t\t// try it as a File reference\n\t\t\tvar asFileReference = tryAsFileReference( jarFileReference, jarFileReference );\n\t\t\tif ( asFileReference != null ) {\n\t\t\t\treturn asFileReference;\n\t\t\t}\n\n\t\t\t// try it as a path relative to the container\n\t\t\tfinal URL relativeReference = urlClassLoader.getResource( jarFileReference );\n\t\t\tif ( relativeReference != null ) {\n\t\t\t\treturn relativeReference;\n\t\t\t}\n\t\t}\n\n\t\tthrow new HibernateException( \"Could not resolve jar-file: \" + jarFileReference );\n\t}\n\n\tprivate static URL tryAsFileReference(String jarFileReference, String trimmed) {\n\t\tfinal File jarFile = new File( trimmed );\n\t\ttry {\n\t\t\tif ( jarFile.exists() ) {\n\t\t\t\treturn jarFile.toURI().toURL();\n\t\t\t}\n\t\t}\n\t\tcatch (MalformedURLException ignore) {\n\t\t}\n\t\treturn null;\n\t}\n\n\n\tpublic static URL asFileReference(String jarFileReference, String trimmed) {\n\t\tfinal File jarFile = new File( trimmed );\n\t\tif ( !jarFile.exists() ) {","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ArchiveHelper.java#L136-L172","documentation":"When Hibernate resolves a <jar-file> reference, ArchiveHelper.resolveJarFileReference tries the string first as a file path/URL (tryAsFileReference) and then as a classloader-relative resource. If neither works it throws HibernateException 'Could not resolve jar-file' — the referenced jar cannot be found by any available mechanism.","triggerScenarios":"A persistence.xml <jar-file>lib/my-entities.jar</jar-file> entry whose path matches neither an existing file on disk nor a classloader-visible resource: misspelled name, wrong relative base, or the jar never shipped.","commonSituations":"Moving a persistence unit from an EE server (where jar-file resolves relative to the deployment) to Java SE; builds that never package the entities jar; relative paths that break in Docker or different working directories.","solutions":["Reference the jar by an absolute path or file: URL that is valid on the target machine.","Put the jar on the classpath and reference it relative to the classpath root.","Prefer explicit <class> entries or annotation scanning over <jar-file> to avoid path resolution entirely."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"static boolean jarFileResolvable(String ref, ClassLoader cl) {\n    return new File(ref).exists() || cl.getResource(ref) != null;\n}","typeGuard":null,"tryCatchPattern":"Catch org.hibernate.HibernateException during archive resolution, match 'Could not resolve jar-file', and report the reference plus the deployment's absolute root path.","preventionTips":["Validate <jar-file> entries against the actual deployment layout for each environment.","Prefer absolute paths or classpath-relative references.","Consider replacing <jar-file> with explicit <class> entries."],"tags":["hibernate","persistence-xml","jar-file","classpath","deployment"],"backgroundTag":"jar-file-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}