What causes "Mapping (%s) not found : %s" in hibernate/hibernate-orm?

Verify the archive opens: jar tf myapp.jar | head (or unzip -l) - a CRC/zip error confirms corruption

hibernate/hibernate-orm · error · MappingNotFoundException

Mapping (%s) not found : %s

Error message

Mapping (%s) not found : %s

What it means

JarFileEntryXmlSource scans a jar for *.hbm.xml entries; any IOException while opening or reading the jar is wrapped in MappingNotFoundException with a JAR-type Origin naming the jar path. The jar could not be opened or enumerated - unlike the plain file case, this often means unreadable/corrupt rather than absent.

Source

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

	 */
	public static void fromJar(
			File jar,
			MappingBinder mappingBinder,
			Consumer<Binding<? extends JaxbBindableMappingDescriptor>> consumer) {
		JAXB_LOGGER.tracef( "Seeking mapping documents in jar file: %s", jar.getName() );
		final var origin = new Origin( SourceType.JAR, jar.getAbsolutePath() );
		try ( var jarFile = new JarFile( jar ) ) {
			final var entries = jarFile.entries();
			while ( entries.hasMoreElements() ) {
				final var jarEntry = entries.nextElement();
				if ( jarEntry.getName().endsWith(".hbm.xml") ) {
					JAXB_LOGGER.tracef( "Found 'hbm.xml' mapping in jar: %s", jarEntry.getName() );
					consumer.accept( fromJarEntry( jarFile, jarEntry, origin, mappingBinder ) );
				}
			}
		}
		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(

View on GitHub (pinned to fad1729dce)

Solutions

Verify the archive opens: jar tf myapp.jar | head (or unzip -l) - a CRC/zip error confirms corruption
Re-download or rebuild the jar from a trusted source and redeploy
Check file permissions and, on Windows, that nothing holds an exclusive lock
If you only need specific mappings inside the jar, extract them and register them as files/resources instead

Example fix

# before: corrupt jar fails during scan
sources.addJar(new File("libs/legacy-mappings.jar"));

# after: verify, then re-register a good copy
$ jar tf libs/legacy-mappings.jar   # exposes zip error
$ mvn deploy:deploy-file ...        # or re-copy from source
sources.addJar(new File("libs/legacy-mappings.jar"));

Defensive patterns

Strategy: validation

Validate before calling

// verify the jar opens cleanly before registering it
File jar = new File(path);
if (!jar.isFile()) throw new IllegalArgumentException("Not a jar file: " + jar.getAbsolutePath());
try (var jf = new java.util.jar.JarFile(jar)) {
    if (!jf.entries().hasMoreElements()) throw new IllegalArgumentException("Empty jar: " + path);
} catch (IOException e) {
    throw new IllegalArgumentException("Unreadable/corrupt jar: " + path, e);
}

Try / catch

try {
    metadataSources.addJar(new File(path));
} catch (MappingNotFoundException e) {
    // Origin names the jar; verify with 'jar tf' - corrupt archives must be re-fetched
    log.error("Cannot read mapping jar: {}", e.getMessage(), e);
    throw e;
}

Prevention

Verify jar integrity (jar tf / checksums) during deployment
Extract-and-register individual mapping files when only a few are needed
Avoid registering jars whose lifecycle is managed by another process

When it happens

Trigger: addJar(new File(...)) where the path is not a valid zip/jar, the file is locked by another process (Windows), or the jar was truncated during download/copy.

Common situations: Corrupt artifacts pulled from broken mirrors; partially copied jars in Docker layers; fat/uber-jar repackaging that damaged entries; permissions on the jar file.

Related errors

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