{"record":{"id":"25b012a82c03e6c8","repo":"hibernate/hibernate-orm","slug":"error-accessing-nested-jar-archive","errorCode":null,"errorMessage":"Error accessing nested jar archive [{}]","messagePattern":"Error accessing nested jar archive \\[(.+?)\\]","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/NestedJarDescriptor.java","lineNumber":80,"sourceCode":"\t\t\t\t\t\t\tjarEntryName,\n\t\t\t\t\t\t\tnew URI( archiveUrl + \"!/\" + jarEntryName ),\n\t\t\t\t\t\t\tbuildByteBasedInputStreamAccess( jarEntryName, jarInputStream )\n\t\t\t\t\t) );\n\t\t\t\t}\n\t\t\t\tcatch (URISyntaxException e) {\n\t\t\t\t\tthrow new ArchiveException(\n\t\t\t\t\t\t\tString.format( Locale.ROOT,\n\t\t\t\t\t\t\t\t\t\"Unable to create archive entry URI: %s - %s\",\n\t\t\t\t\t\t\t\t\tarchiveUrl,\n\t\t\t\t\t\t\t\t\tjarEntry.getName()\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\te\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\t}\n\n\t@Override\n\tpublic @Nullable ArchiveEntry findEntry(String relativePath) {\n\t\ttry (final InputStream is = new BufferedInputStream( archiveUrl.openStream() );\n\t\t\tfinal JarInputStream jarInputStream = new JarInputStream( is )) {\n\t\t\tJarEntry jarEntry;\n\t\t\twhile ( ( jarEntry = jarInputStream.getNextJarEntry() ) != null ) {\n\t\t\t\tfinal String jarEntryName = jarEntry.getName();\n\t\t\t\tif ( relativePath.equals( jarEntryName ) ) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\treturn new ArchiveEntryImpl(\n\t\t\t\t\t\t\t\tjarEntryName,\n\t\t\t\t\t\t\t\tjarEntryName,\n\t\t\t\t\t\t\t\tnew URI( archiveUrl + \"!/\" + jarEntryName ),\n\t\t\t\t\t\t\t\tbuildByteBasedInputStreamAccess( jarEntryName, jarInputStream )\n\t\t\t\t\t\t);","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/NestedJarDescriptor.java#L62-L98","documentation":"Thrown when opening or reading a nested jar archive fails with an IOException during visitEntries: either archiveUrl.openStream() cannot supply a stream (the protocol handler cannot open the connection, or the resource is gone), or the JarInputStream read fails (corrupt or truncated archive). The original IOException is attached as the cause.","triggerScenarios":"visitEntries() on a NestedJarDescriptor whose archive URL points to a jar that was deleted or replaced between discovery and scan; a corrupt/truncated jar; a URL protocol (bundle://, vfs://, custom scheme) whose stream cannot be opened; file permissions denying read access.","commonSituations":"Hot redeploy while another thread is still scanning; partially copied jars in temp/repo directories; OSGi or app-server protocols without usable stream handlers; locked files on Windows during redeploy.","solutions":["Verify the jar exists and can be opened at scan time (open it yourself once before bootstrap)","Copy the archive to a stable local file location and point Hibernate at that copy","Stop the old SessionFactory before replacing/redeploying jars; avoid scanning during redeploy","For exotic URL protocols, register a URLStreamHandlerFactory or use file-based archives"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// prove the archive is openable and looks like a jar before bootstrap\nstatic void assertReadableJar(URL url) throws IOException {\n    try (InputStream in = new BufferedInputStream(url.openStream());\n         JarInputStream jar = new JarInputStream(in)) {\n        if (jar.getNextJarEntry() == null && jar.getManifest() == null)\n            throw new IOException(\"Not a readable jar: \" + url);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata.scanEnvironment().getExplicitFileReferences()...; // or SessionFactory build\n} catch (ArchiveException e) {\n    if (e.getCause() instanceof IOException io) {\n        // distinguish deleted/locked file vs corrupt jar via io.getMessage()\n        throw new IllegalStateException(\"Archive unreadable during scan: \" + io.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Do not replace jars while a SessionFactory is being built","Verify artifact integrity after CI copy/download steps"],"tags":["hibernate","nested-jar","ioexception","archive-scanning","redeploy"],"backgroundTag":"jar-file-io-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}