{"record":{"id":"b059631abf043fe3","repo":"hibernate/hibernate-orm","slug":"unable-to-handle-discovered-mapping-file","errorCode":null,"errorMessage":"Unable to handle discovered mapping file : {}","messagePattern":"Unable to handle discovered mapping file : (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java","lineNumber":222,"sourceCode":"\t\t\tbootRegistry.close();\n\t\t\tcleanup();\n\t\t\tthrow throwable;\n\t\t}\n\t}\n\n\tprivate void applyScanning(HibernatePersistenceConfiguration cfg, MetadataSources metadataSources, StandardServiceRegistry standardServiceRegistry) {\n\t\tvar scanningResult = performScanning( cfg, standardServiceRegistry );\n\n\t\tscanningResult.discoveredPackages().forEach( metadataSources::addPackage );\n\n\t\tscanningResult.discoveredClasses().forEach( metadataSources::addAnnotatedClassName );\n\n\t\tscanningResult.mappingFiles().forEach( (mappingFileUri) -> {\n\t\t\ttry {\n\t\t\t\tmetadataSources.addURL( mappingFileUri.toURL() );\n\t\t\t}\n\t\t\tcatch (MalformedURLException e) {\n\t\t\t\tthrow new HibernateException( \"Unable to handle discovered mapping file : \" + mappingFileUri, e );\n\t\t\t}\n\t\t} );\n\t}\n\n\tprivate MergedSettings createMergedSettings(\n\t\t\t@Nonnull HibernatePersistenceConfiguration cfg,\n\t\t\t@Nonnull StandardServiceRegistryBuilder standardRegistryBuilder) {\n\t\tvar mergedSettings = new MergedSettings();\n\n\t\tmergedSettings.getConfigurationValues().putAll( cfg.properties() );\n\t\tcollectSchemaManagementActions( cfg, mergedSettings.getConfigurationValues()::putIfAbsent );\n\t\tmergedSettings.getConfigurationValues().put( PERSISTENCE_UNIT_NAME, cfg.name() );\n\n\t\t// see if the persistence.xml settings named a Hibernate config file\n\t\tfinal String cfgXmlResourceName = getCfgXmlResourceName( Collections.emptyMap(), mergedSettings );\n\t\tif ( isNotEmpty( cfgXmlResourceName ) ) {\n\t\t\tprocessHibernateConfigXmlResources( standardRegistryBuilder, mergedSettings, cfgXmlResourceName );\n\t\t}","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java#L204-L240","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Declare the mapping files explicitly in persistence.xml (<mapping-file>) and disable scanning (<exclude-unlisted-classes>true</exclude-unlisted-classes>)","Upgrade the Hibernate / container integration so scanning resolves the scheme (VFS support has improved across versions)","If you control the classloader, expose resource URLs through a java.net-supported protocol (file:, jar:)"],"exampleFix":"<!-- before: rely on scanning over vfs:/ nested URLs -->\n<!-- after: declare mapping files explicitly, disable scanning -->\n<persistence-unit name=\"main\">\n  <exclude-unlisted-classes>true</exclude-unlisted-classes>\n  <mapping-file>META-INF/orm.xml</mapping-file>\n</persistence-unit>","handlingStrategy":"try-catch","validationCode":"// Pre-flight: can every scanned mapping URI become a java.net.URL?\nfor (java.net.URI uri : scannedMappingFileUris) {\n    try { uri.toURL(); }\n    catch (java.net.MalformedURLException e) {\n        throw new IllegalStateException(\"Unsupported protocol in \" + uri + \" - declare mapping files explicitly\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    emf = Persistence.createEntityManagerFactory(\"main\");\n} catch (org.hibernate.HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Unable to handle discovered mapping file\")) {\n        // switch to explicit <mapping-file> entries + exclude-unlisted-classes, or upgrade the container integration\n    }\n    throw e;\n}","preventionTips":["In VFS/OSGi containers, always declare mapping files explicitly rather than relying on scanning","Keep the Hibernate container adapter (WildFly/OSGi integration) in sync with hibernate-core","Smoke-test EMF bootstrap on the target application server, not only in-JVM"],"tags":["jpa","scanning","classloader","url"],"backgroundTag":"unsupported-url-scheme","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}