{"record":{"id":"7c3c69cf1f396fda","repo":"hibernate/hibernate-orm","slug":"unable-to-open-inputstream-for-jar-file-entry-s","errorCode":null,"errorMessage":"Unable to open InputStream for jar file entry [%s : %s]","messagePattern":"Unable to open InputStream for jar file entry \\[(.+?) : (.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/JarFileEntryXmlSource.java","lineNumber":74,"sourceCode":"\t\tcatch ( IOException e ) {\n\t\t\tthrow new MappingNotFoundException( e, origin );\n\t\t}\n\t}\n\n\t/**\n\t * Create a mapping {@linkplain Binding binding} from a JAR file entry.\n\t */\n\tpublic static Binding<? extends JaxbBindableMappingDescriptor> fromJarEntry(\n\t\t\tJarFile jarFile,\n\t\t\tZipEntry jarFileEntry,\n\t\t\tOrigin origin,\n\t\t\tMappingBinder mappingBinder) {\n\t\tfinal InputStream stream;\n\t\ttry {\n\t\t\tstream = jarFile.getInputStream( jarFileEntry );\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\"Unable to open InputStream for jar file entry [%s : %s]\",\n\t\t\t\t\t\t\tjarFile.getName(),\n\t\t\t\t\t\t\tjarFileEntry.getName()\n\t\t\t\t\t),\n\t\t\t\t\te,\n\t\t\t\t\torigin\n\t\t\t);\n\t\t}\n\n\t\treturn InputStreamXmlSource.fromStream( stream, origin, true, mappingBinder );\n\t}\n}\n","sourceCodeStart":56,"sourceCodeEnd":88,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/JarFileEntryXmlSource.java#L56-L88","documentation":"Hibernate wraps an IOException raised by JarFile.getInputStream(ZipEntry) in a MappingException while reading a mapping document (hbm.xml/orm.xml) packaged inside a JAR. The Origin in the exception names the JAR and entry that failed. It is an I/O-level failure on an archive Hibernate already opened, not a mapping-content problem.","triggerScenarios":"Bootstrap paths that scan JARs for mappings: persistence.xml <jar-file> entries, hibernate.archive.autodetection, or Configuration.addJar(...). It fires when JarFile.getInputStream(entry) throws: corrupt/truncated ZIP, entry stored with an unsupported compression method, the JarFile already closed, or a nested JAR (e.g. inside a Spring Boot fat jar) that cannot be read as a plain ZipEntry.","commonSituations":"Partially downloaded or corrupted dependency JAR in the local repo; shading/minimization stripping entries; nested-jar packaging where the URL points inside another JAR; Windows file locks or permission changes on the JAR between scan and read.","solutions":["Verify archive integrity: 'unzip -t myapp.jar' and 'jar tf' to confirm the entry exists and is readable","Rebuild or re-download the affected JAR (corrupt artifacts are the most common cause)","For fat/nested jars, stop scanning the archive as a jar-file; register mappings as <class>/<mapping-file> classpath resources instead","Check file permissions and that nothing (antivirus, another process) holds an exclusive lock on the JAR"],"exampleFix":"// before (persistence.xml)\n<jar-file>lib/entities.jar</jar-file>  <!-- nested inside a fat jar -->\n\n// after\n<class>com.acme.Item</class>\n<mapping-file>META-INF/item-orm.xml</mapping-file>","handlingStrategy":"validation","validationCode":"try (JarFile jar = new JarFile(pathToJar)) {\n    ZipEntry entry = jar.getEntry(\"META-INF/mappings/item.hbm.xml\");\n    if (entry == null) throw new IllegalStateException(\"mapping entry missing in \" + pathToJar);\n    try (InputStream in = jar.getInputStream(entry)) {\n        if (in.readAllBytes().length == 0) throw new IllegalStateException(\"empty mapping entry\");\n    }\n}","typeGuard":null,"tryCatchPattern":"catch (MappingException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof IOException io) {\n        // I/O failure on the jar/entry named in e.getOrigin(); fail bootstrap with a clear message\n        throw new IllegalStateException(\"Unreadable mapping jar entry: \" + e.getOrigin(), e);\n    }\n    throw e;\n}","preventionTips":["Run 'unzip -t' / 'jar tf' over mapping jars as a CI step","Prefer classpath <mapping-file> registration over <jar-file> scanning in fat-jar deployments","Open JarFiles with try-with-resources so they cannot be closed before binding"],"tags":["jpa","bootstrap","jar","mapping-file","io"],"backgroundTag":"corrupt-archive-read","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}