{"record":{"id":"6ad9d8a13354b13c","repo":"hibernate/hibernate-orm","slug":"not-supported","errorCode":null,"errorMessage":"Not supported.","messagePattern":"Not supported\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/NestedJarDescriptor.java","lineNumber":122,"sourceCode":"\t\t\t\t\t\t\t\t\t\tarchiveUrl,\n\t\t\t\t\t\t\t\t\t\tjarEntry.getName()\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\te\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new ArchiveException( \"Error accessing nested jar archive [\" + archiveUrl + \"]\", e );\n\t\t}\n\n\t\treturn null;\n\t}\n\n\t@Override @Nonnull\n\tpublic ArchiveDescriptor resolveJarFileReference(@Nonnull String jarFileReference) {\n\t\tthrow new UnsupportedOperationException( \"Not supported.\" );\n\t}\n}\n","sourceCodeStart":104,"sourceCodeEnd":125,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/NestedJarDescriptor.java#L104-L125","documentation":"NestedJarDescriptor.resolveJarFileReference unconditionally throws UnsupportedOperationException because an archive that is itself nested (jar:...!/...) cannot, in turn, resolve further <jar-file/> references. You only reach it when Hibernate processes a jar-file reference while the current archive descriptor is a nested jar.","triggerScenarios":"A persistence unit whose scanning root is a nested jar (e.g. jar:file:app.jar!/WEB-INF/classes/) that itself declares a <jar-file/> entry; or SPI-level code calling ArchiveDescriptor.resolveJarFileReference on a descriptor built from a nested-jar URL.","commonSituations":"Executable/fat jars (Spring Boot) where persistence.xml lives inside a nested archive and still lists <jar-file/> entries copied from a legacy WAR layout; unusual EAR packaging after migration.","solutions":["Remove the <jar-file/> entry from the persistence unit inside the nested archive","Repackage so the persistence unit and the jars it lists are top-level sibling archives","Replace <jar-file/> with explicit <class> entries or rely on automatic entity scanning"],"exampleFix":"// before (persistence.xml inside a nested jar, e.g. BOOT-INF/classes/META-INF/persistence.xml)\n<jar-file>entities.jar</jar-file>\n\n// after: list entities explicitly\n<class>com.acme.entity.Customer</class>\n<class>com.acme.entity.Order</class>","handlingStrategy":"try-catch","validationCode":"// guard: a persistence unit reached through a nested-jar URL must not declare <jar-file/>\nvar puUrl = clazz.getResource(\"/META-INF/persistence.xml\");\nif (puUrl != null && \"jar\".equals(puUrl.getProtocol())\n        && puUrl.toString().contains(\"!/\")\n        && readText(puUrl).contains(\"<jar-file\")) {\n    throw new IllegalStateException(\n        \"persistence.xml inside a nested archive must not use <jar-file/>; use <class> entries\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    ArchiveDescriptor resolved = descriptor.resolveJarFileReference(ref);\n} catch (UnsupportedOperationException e) {\n    throw new IllegalArgumentException(\n        \"Cannot resolve <jar-file/> \" + ref + \" from a nested archive; repackage as top-level jars\", e);\n}","preventionTips":["In fat-jar layouts, always prefer explicit <class> entries or scanning over <jar-file/>","Smoke-test bootstrap from the exact packaged artifact (java -jar), not just the IDE classpath"],"tags":["hibernate","nested-jar","unsupported-operation","persistence-xml","fat-jar"],"backgroundTag":"unsupported-archive-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}