{"record":{"id":"150d90a51a4a24dd","repo":"hibernate/hibernate-orm","slug":"error-accessing-jar-file-rootfilepath","errorCode":null,"errorMessage":"Error accessing jar file [<rootFilePath>]","messagePattern":"Error accessing jar file \\[<rootFilePath>\\]","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java","lineNumber":171,"sourceCode":"\t\t\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\t\t\"Unable to access stream from jar file [%s] for entry [%s]\",\n\t\t\t\t\t\t\t\t\tjarFile.getName(),\n\t\t\t\t\t\t\t\t\tzipEntry.getName()\n\t\t\t\t\t\t\t)\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\t// todo (jpa4) : for now, pass null\n\t\t\t\tentryConsumer.accept( new ArchiveEntryImpl(\n\t\t\t\t\t\tname,\n\t\t\t\t\t\trelativeName,\n\t\t\t\t\t\tnew URL( \"jar:\" + entryUriBase + \"!/\" + relativeName ).toURI(),\n\t\t\t\t\t\tinputStreamAccess\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 jar file [\" + rootFile.getAbsolutePath() + \"]\", e );\n\t\t}\n\t\tcatch (URISyntaxException e) {\n\t\t\tthrow new ArchiveException( \"Unable to create archive entry URI\", e );\n\t\t}\n\t}\n\n\n\t@Override\n\tpublic @Nullable ArchiveEntry findEntry(String relativePath) {\n\t\tfinal File file = resolveRelativePath( relativePath );\n\t\tif ( file == null ) {\n\t\t\treturn null;\n\t\t}\n\t\tfinal String name = file.getAbsolutePath();\n\t\tfinal InputStreamAccess inputStreamAccess = new FileInputStreamAccess( name, file );\n\t\treturn new ArchiveEntryImpl( name, relativePath, file.toURI(), inputStreamAccess );\n\t}\n","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/archive/internal/ExplodedArchiveDescriptor.java#L153-L189","documentation":"ExplodedArchiveDescriptor.visitArchive wraps any IOException raised while scanning the root file (opening it as a jar, iterating entries, building entry URIs) as ArchiveException 'Error accessing jar file'. Unlike its sibling message, the IOException is attached as the cause — always inspect getCause() for the real reason.","triggerScenarios":"The root path handed to the exploded-archive descriptor actually names a jar file, and reading it throws IOException: missing permissions, file removed or locked during the scan, or a truncated archive.","commonSituations":"A jar path configured where an exploded directory was expected (archive-type mismatch in the scan setup); exploded WARs containing jars scanned during hot redeploys; permission-restricted containers.","solutions":["Read the chained cause and fix the underlying I/O problem (permissions, missing file, lock).","Correct the scan configuration so jar paths are handled by the jar archive descriptor and directories by the exploded one.","Grant the server user read access to the whole deployment tree and avoid mutating it during startup."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"Catch org.hibernate.boot.archive.spi.ArchiveException around bootstrap and always inspect getCause() — the chained IOException holds the real reason (permission denied, file missing, lock). Fix the underlying access problem; no retry helps until it is resolved.","preventionTips":["Match scan configuration to the artifact type: directories as exploded, jars as jar archives.","Grant read access to the full deployment tree for the server user.","Do not delete or rewrite deployed files while the application boots."],"tags":["hibernate","archive-scanning","io","deployment","permissions"],"backgroundTag":"archive-read-io-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}