{"record":{"id":"a658e669f615a83b","repo":"hibernate/hibernate-orm","slug":"unable-to-resolve-jar-file-reference-a658e6","errorCode":null,"errorMessage":"Unable to resolve <jar-file/> reference - {}","messagePattern":"Unable to resolve <jar-file/> reference - (.+?)","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java","lineNumber":266,"sourceCode":"\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":248,"sourceCodeEnd":269,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java#L248-L269","documentation":"Thrown during Hibernate bootstrap while it resolves <jar-file/> elements from persistence.xml. Hibernate first tries to interpret the reference as a relative URL, then falls back to ArchiveHelper.standardJarFileReferenceResolution (URL or file-path interpretation); if neither yields an archive, this ArchiveException is thrown with the unresolved reference. It means Hibernate has no way to open the listed managed-class jar at all.","triggerScenarios":"Building a SessionFactory/EntityManagerFactory from a persistence.xml whose <jar-file> value is neither a parseable URL nor an existing file-system path — e.g. <jar-file>libs/entities.jar</jar-file> when the file is not at that location relative to the persistence unit root, or a classpath:-style reference that Hibernate does not expand.","commonSituations":"Running inside Spring Boot fat/executable jars where jar-inside-jar references cannot be resolved; containers that unpack deployments differently than the dev environment; typos in the jar-file path; referencing a jar that is simply not deployed.","solutions":["Correct the <jar-file/> value to an absolute file path or valid URL that exists at runtime","Drop <jar-file/> and list entity classes explicitly with <class> elements instead","With Spring Boot, avoid <jar-file/> entirely and let Spring's entity scanning register the entities","Verify the referenced jar is actually deployed alongside the persistence unit"],"exampleFix":"// before (persistence.xml)\n<persistence-unit name=\"pu\">\n    <jar-file>entities.jar</jar-file> <!-- relative, not resolvable from the PU root -->\n</persistence-unit>\n\n// after\n<persistence-unit name=\"pu\">\n    <jar-file>file:///opt/app/lib/entities.jar</jar-file> <!-- absolute URL that exists -->\n</persistence-unit>","handlingStrategy":"validation","validationCode":"// verify every <jar-file/> entry before building the EntityManagerFactory\nstatic boolean jarReferenceResolvable(String ref) {\n    if (new File(ref).isFile()) return true;\n    try { new URL(ref); return true; }\n    catch (MalformedURLException e) { return false; }\n}\n// usage:\nfor (String ref : persistenceUnitJarFileEntries()) {\n    if (!jarReferenceResolvable(ref))\n        throw new IllegalArgumentException(\"Unresolvable <jar-file/> entry: \" + ref);\n}","typeGuard":null,"tryCatchPattern":"try {\n    EntityManagerFactory emf = Persistence.createEntityManagerFactory(\"pu\");\n} catch (ArchiveException e) {\n    // message ends with the unresolved reference; surface it in the bootstrap error report\n    throw new IllegalStateException(\"Bad <jar-file/> in persistence.xml: \" + e.getMessage(), e);\n}","preventionTips":["Prefer absolute URLs or drop <jar-file/> in favor of <class> entries or scanning","Bootstrap once in a smoke test with the exact production packaging layout"],"tags":["hibernate","persistence-xml","jar-file","bootstrap","archive-scanning"],"backgroundTag":"classpath-resource-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}