hibernate/hibernate-orm · error · HibernateException

Unable to handle discovered mapping file : {}

Error message

Unable to handle discovered mapping file : {}

What it means

During persistence-unit scanning, EntityManagerFactoryBuilderImpl.convert each discovered mapping-file URI into a java.net.URL with URI.toURL(). When the classpath resource uses a protocol java.net.URL cannot handle, toURL() throws MalformedURLException and bootstrap aborts with this HibernateException naming the offending mappingFileUri. The problem is the URL scheme, not the file's content.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java:222

			bootRegistry.close();
			cleanup();
			throw throwable;
		}
	}

	private void applyScanning(HibernatePersistenceConfiguration cfg, MetadataSources metadataSources, StandardServiceRegistry standardServiceRegistry) {
		var scanningResult = performScanning( cfg, standardServiceRegistry );

		scanningResult.discoveredPackages().forEach( metadataSources::addPackage );

		scanningResult.discoveredClasses().forEach( metadataSources::addAnnotatedClassName );

		scanningResult.mappingFiles().forEach( (mappingFileUri) -> {
			try {
				metadataSources.addURL( mappingFileUri.toURL() );
			}
			catch (MalformedURLException e) {
				throw new HibernateException( "Unable to handle discovered mapping file : " + mappingFileUri, e );
			}
		} );
	}

	private MergedSettings createMergedSettings(
			@Nonnull HibernatePersistenceConfiguration cfg,
			@Nonnull StandardServiceRegistryBuilder standardRegistryBuilder) {
		var mergedSettings = new MergedSettings();

		mergedSettings.getConfigurationValues().putAll( cfg.properties() );
		collectSchemaManagementActions( cfg, mergedSettings.getConfigurationValues()::putIfAbsent );
		mergedSettings.getConfigurationValues().put( PERSISTENCE_UNIT_NAME, cfg.name() );

		// see if the persistence.xml settings named a Hibernate config file
		final String cfgXmlResourceName = getCfgXmlResourceName( Collections.emptyMap(), mergedSettings );
		if ( isNotEmpty( cfgXmlResourceName ) ) {
			processHibernateConfigXmlResources( standardRegistryBuilder, mergedSettings, cfgXmlResourceName );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Declare the mapping files explicitly in persistence.xml (<mapping-file>) and disable scanning (<exclude-unlisted-classes>true</exclude-unlisted-classes>)
2. Upgrade the Hibernate / container integration so scanning resolves the scheme (VFS support has improved across versions)
3. If you control the classloader, expose resource URLs through a java.net-supported protocol (file:, jar:)

Example fix

<!-- before: rely on scanning over vfs:/ nested URLs -->
<!-- after: declare mapping files explicitly, disable scanning -->
<persistence-unit name="main">
  <exclude-unlisted-classes>true</exclude-unlisted-classes>
  <mapping-file>META-INF/orm.xml</mapping-file>
</persistence-unit>

// Pre-flight: can every scanned mapping URI become a java.net.URL?
for (java.net.URI uri : scannedMappingFileUris) {
    try { uri.toURL(); }
    catch (java.net.MalformedURLException e) {
        throw new IllegalStateException("Unsupported protocol in " + uri + " - declare mapping files explicitly");
    }
}

try {
    emf = Persistence.createEntityManagerFactory("main");
} catch (org.hibernate.HibernateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to handle discovered mapping file")) {
        // switch to explicit <mapping-file> entries + exclude-unlisted-classes, or upgrade the container integration
    }
    throw e;
}

When it happens

Trigger: Deployments where scanned resources come from virtual filesystems - JBoss VFS (vfs://...), OSGi bundles (bundle://...), or custom/legacy classloaders exposing URI schemes unsupported by java.net.URL - and the unit relies on auto-scanning to pick up mapping files.

Common situations: War/EAR deployed on WildFly/JBoss with VFS URLs; OSGi containers; exotic application servers; older Spring Boot nested-jar edge cases; custom classloaders in plugin systems.

Related errors

• [persistence unit: %s] Enhancement requires a temp class loa
• Enhancement requires a temp class loader, but none was given
• Unable to instantiate ScanningProvider `%s`
• Unable to instantiate Scanner `%s`
• Class '<componentClassName>' is an '@Embeddable' type and ma

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