hibernate/hibernate-orm · error · MappingException

Unable to open InputStream for jar file entry [%s : %s]

Error message

Unable to open InputStream for jar file entry [%s : %s]

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/JarFileEntryXmlSource.java:74

		catch ( IOException e ) {
			throw new MappingNotFoundException( e, origin );
		}
	}

	/**
	 * Create a mapping {@linkplain Binding binding} from a JAR file entry.
	 */
	public static Binding<? extends JaxbBindableMappingDescriptor> fromJarEntry(
			JarFile jarFile,
			ZipEntry jarFileEntry,
			Origin origin,
			MappingBinder mappingBinder) {
		final InputStream stream;
		try {
			stream = jarFile.getInputStream( jarFileEntry );
		}
		catch (IOException e) {
			throw new MappingException(
					String.format(
							"Unable to open InputStream for jar file entry [%s : %s]",
							jarFile.getName(),
							jarFileEntry.getName()
					),
					e,
					origin
			);
		}

		return InputStreamXmlSource.fromStream( stream, origin, true, mappingBinder );
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

  1. Verify archive integrity: 'unzip -t myapp.jar' and 'jar tf' to confirm the entry exists and is readable
  2. Rebuild or re-download the affected JAR (corrupt artifacts are the most common cause)
  3. For fat/nested jars, stop scanning the archive as a jar-file; register mappings as <class>/<mapping-file> classpath resources instead
  4. Check file permissions and that nothing (antivirus, another process) holds an exclusive lock on the JAR

Example fix

// before (persistence.xml)
<jar-file>lib/entities.jar</jar-file>  <!-- nested inside a fat jar -->

// after
<class>com.acme.Item</class>
<mapping-file>META-INF/item-orm.xml</mapping-file>
Defensive patterns

Strategy: validation

Validate before calling

try (JarFile jar = new JarFile(pathToJar)) {
    ZipEntry entry = jar.getEntry("META-INF/mappings/item.hbm.xml");
    if (entry == null) throw new IllegalStateException("mapping entry missing in " + pathToJar);
    try (InputStream in = jar.getInputStream(entry)) {
        if (in.readAllBytes().length == 0) throw new IllegalStateException("empty mapping entry");
    }
}

Try / catch

catch (MappingException e) {
    Throwable cause = e.getCause();
    if (cause instanceof IOException io) {
        // I/O failure on the jar/entry named in e.getOrigin(); fail bootstrap with a clear message
        throw new IllegalStateException("Unreadable mapping jar entry: " + e.getOrigin(), e);
    }
    throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/7c3c69cf1f396fda. Report an issue: GitHub.