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

hibernate/hibernate-orm · error · MappingNotFoundException

Mapping (%s) not found : %s

Error message

Mapping (%s) not found : %s

What it means

UrlXmlSource.fromResource asks ClassLoaderService.locateResource for the mapping resource name; when it returns null, Hibernate throws MappingNotFoundException with 'Mapping (RESOURCE) not found : <name>'. The exception's Origin records exactly the resource path Hibernate tried to load.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/UrlXmlSource.java:42

 * @see MappingBinder
 *
 * @author Steve Ebersole
 */
public class UrlXmlSource {
	/**
	 * Create a mapping {@linkplain Binding binding} from a classpath resource (via URL).
	 *
	 * @see #fromUrl(URL, Origin, MappingBinder)
	 */
	public static Binding<? extends JaxbBindableMappingDescriptor> fromResource(
			String resourceName,
			ClassLoaderService classLoaderService,
			MappingBinder mappingBinder) {
		JAXB_LOGGER.tracef( "Reading mappings from resource: %s", resourceName );
		final var origin = new Origin( SourceType.RESOURCE, resourceName );
		final var url = classLoaderService.locateResource( resourceName );
		if ( url == null ) {
			throw new MappingNotFoundException( origin );
		}
		return fromUrl( url, origin, mappingBinder );
	}

	/**
	 * Create a mapping {@linkplain Binding binding} from a URL
	 *
	 * @see #fromUrl(URL, Origin, MappingBinder)
	 */
	public static Binding<? extends JaxbBindableMappingDescriptor> fromUrl(
			URL url,
			MappingBinder mappingBinder) {
		return fromUrl( url, new Origin( SourceType.URL, url.toExternalForm() ), mappingBinder );
	}

	/**
	 * Create a mapping {@linkplain Binding binding} from a URL
	 *

View on GitHub (pinned to fad1729dce)

Solutions

Check the path from the same process: Thread.currentThread().getContextClassLoader().getResource("<name>") — if it returns null, fix the path or packaging
Use a path relative to the classpath root (no leading slash) and match directory case exactly
Inspect the packaged artifact (jar tf target/app.jar) to confirm the file was actually included
For app servers, ensure the module containing the mapping is visible to the module bootstrapping Hibernate

Example fix

// before
configuration.addResource("Mappings/Item.hbm.xml"); // actual file: mappings/item.hbm.xml

// after
configuration.addResource("mappings/item.hbm.xml");

Defensive patterns

Strategy: validation

Validate before calling

String name = "mappings/item.hbm.xml";
if (Thread.currentThread().getContextClassLoader().getResource(name) == null
        && MappingClass.class.getClassLoader().getResource(name) == null) {
    throw new IllegalStateException("mapping resource not on classpath: " + name);
}
configuration.addResource(name);

Try / catch

catch (MappingNotFoundException e) {
    // e.getOrigin().getName() is the exact path Hibernate tried
    throw new IllegalStateException("Mapping not found on classpath: " + e.getOrigin(), e);
}

Prevention

Always derive mapping paths from constants shared with the resource layout
Add a packaging assertion (jar tf check) in CI that mapping files exist at expected paths
Prefer classpath-root-relative paths without leading slashes

When it happens

Trigger: Configuration.addResource("mappings/Item.hbm.xml"), persistence.xml <mapping-file>META-INF/orm.xml</mapping-file>, or programmatic MetadataBuilder resource adds where the path is not resolvable by the current classloaders: wrong case, wrong directory, leading slash, file not packaged, or classloader isolation hiding it.

Common situations: Case-sensitive path typo on Linux CI that worked on Windows/macOS; mapping file under src/main/resources excluded by build filters; resource inside a dependency jar not visible to the app-server's classloader hierarchy; path written with a leading '/' in one API and without in another.

Related errors

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