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

Print new File(path).getAbsolutePath() to see where the JVM is actually looking

hibernate/hibernate-orm · error · MappingNotFoundException

Mapping (%s) not found : %s

Error message

Mapping (%s) not found : %s

What it means

FileXmlSource.fromFile was asked to read a mapping from a File whose exists() check returned false, so it threw MappingNotFoundException ('Mapping (%s) not found : %s') with a FILE-type Origin. The path simply does not point at an existing file from the JVM's perspective.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/FileXmlSource.java:39

 *
 * @see MappingBinder
 *
 * @author Steve Ebersole
 */
public class FileXmlSource {
	/**
	 * Create a mapping {@linkplain Binding binding} from a File reference.
	 */
	public static Binding<? extends JaxbBindableMappingDescriptor> fromFile(
			File file,
			MappingBinder mappingBinder) {
		final String filePath = file.getPath();
		JAXB_LOGGER.tracef( "Reading mappings from file: %s", filePath );

		final var origin = new Origin( SourceType.FILE, filePath );

		if ( !file.exists() ) {
			throw new MappingNotFoundException( origin );
		}

		final FileInputStream fis;
		try {
			fis = new FileInputStream( file );
		}
		catch ( FileNotFoundException e ) {
			throw new MappingNotFoundException( e, origin );
		}

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

View on GitHub (pinned to fad1729dce)

Solutions

Print new File(path).getAbsolutePath() to see where the JVM is actually looking
Use an absolute path or construct it from a known root (user.dir, config property)
If the mapping is a classpath resource, use addResource('com/acme/User.hbm.xml') instead of a File
If it is inside a jar, use the jar-entry source, not File

Example fix

// before: relative path, wrong cwd
sources.addFile("src/main/resources/com/acme/User.hbm.xml");

// after: classpath resource
sources.addResource("com/acme/User.hbm.xml");

Defensive patterns

Strategy: validation

Validate before calling

// resolve and check the mapping file before registering it
File f = new File(path);
if (!f.exists()) {
    throw new IllegalArgumentException(
        "Mapping not found: " + path + " (resolved to " + f.getAbsolutePath() + ")");
}
metadataSources.addFile(f.getAbsolutePath());

Try / catch

try {
    metadataSources.addFile(path);
} catch (MappingNotFoundException e) {
    // Origin in the exception names the exact path that failed; log it and fix the path
    log.error("Missing mapping: {}", e.getMessage());
    throw e;
}

Prevention

Prefer addResource with classpath paths over addFile with filesystem paths
Log the resolved absolute path during bootstrap configuration
Centralize mapping path construction in one configuration class

When it happens

Trigger: metadataSources.addFile(path) / equivalent with a wrong relative path: relative paths resolve against the process working directory, not the classpath or project root; also moved/renamed mapping files.

Common situations: Working-directory differences between IDE, test runner, and production; paths like 'src/main/resources/...' that only work at build time; files packaged into jars being referenced as Files.

Related errors

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