{"record":{"id":"ebb09a6195b3727d","repo":"quarkusio/quarkus","slug":"persistence-unit-persistenceunitname-reference","errorCode":null,"errorMessage":"Persistence unit '<persistenceUnitName>' references mapping file '<mappingFileName>', but multiple resources with this path exist in the classpath, and it is not possible to resolve the ambiguity. URLs of matching resources found in the classpath: <mappingFileURLs>","messagePattern":"Persistence unit '<persistenceUnitName>' references mapping file '<mappingFileName>', but multiple resources with this path exist in the classpath, and it is not possible to resolve the ambiguity\\. URLs of matching resources found in the classpath: <mappingFileURLs>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/xml/QuarkusMappingFileParser.java","lineNumber":99,"sourceCode":"            // Multiple classpath resources match this name.\n            // We need to resolve the ambiguity.\n            URL urlInSameMappingFile = null;\n            if (persistenceUnitRootUrl != null) {\n                for (URL url : mappingFileURLs) {\n                    if (!persistenceUnitRootUrl.equals(ArchiveHelper.getJarURLFromURLEntry(url, mappingFileName))) {\n                        continue;\n                    }\n                    if (urlInSameMappingFile == null) {\n                        urlInSameMappingFile = url;\n                    } else {\n                        // Multiple matches in the same JAR...? Can this even happen?\n                        urlInSameMappingFile = null;\n                        break;\n                    }\n                }\n            }\n            if (urlInSameMappingFile == null) {\n                throw new IllegalStateException(\"Persistence unit '\" + persistenceUnitName + \"' references mapping file '\"\n                        + mappingFileName + \"', but multiple resources with this path exist in the classpath,\"\n                        + \" and it is not possible to resolve the ambiguity.\"\n                        + \" URLs of matching resources found in the classpath: \" + mappingFileURLs);\n            }\n            return urlInSameMappingFile;\n        }\n    }\n\n    private static BootstrapServiceRegistry createEmptyBootstrapServiceRegistry() {\n        final ClassLoaderService providedClassLoaderService = FlatClassLoaderService.INSTANCE;\n        // N.B. support for integrators removed\n        final IntegratorService integratorService = new IntegratorService() {\n            @Override\n            public Iterable<Integrator> getIntegrators() {\n                return Collections.emptyList();\n            }\n        };\n        final StrategySelector strategySelector = QuarkusStrategySelectorBuilder.buildSelector(providedClassLoaderService);","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/xml/QuarkusMappingFileParser.java#L81-L117","documentation":"When a persistence unit references a mapping file by name, Quarkus locates it via the class loader. If multiple resources share that path across jars/roots and none can be uniquely attributed to the persistence unit's root, the ambiguity is unresolvable and locateMappingFile (called from url()) throws this IllegalStateException listing all matching URLs.","triggerScenarios":"locateMappingFile finds several URLs via FlatClassLoaderService.locateResources(mappingFileName); the fallback disambiguation by persistence unit root fails (urlInSameMappingFile == null) and it throws.","commonSituations":"Two dependencies both ship a resource at the same path (e.g. both contain orm.xml or META-INF/extra-orm.xml); duplicate classpath entries from IDE or fat-jar packaging; application classes and a library jar both define the mapping file.","solutions":["Exclude the duplicate resource from one dependency (Maven exclusion or resource filtering).","Rename your mapping file so its path is unique on the classpath.","Remove the stale/duplicate jar so only one resource with that path remains.","Keep the mapping file under the persistence unit root so Quarkus can disambiguate it."],"exampleFix":"<!-- before: two jars contain META-INF/extra-orm.xml -->\n<!-- after (pom.xml): exclude the conflicting dependency resource -->\n<exclusion>\n  <groupId>com.example</groupId>\n  <artifactId>duplicate-mappings-lib</artifactId>\n</exclusion>","handlingStrategy":"validation","validationCode":"Enumeration<URL> urls = Thread.currentThread().getContextClassLoader()\n    .getResources(\"META-INF/extra-orm.xml\");\nif (urls.hasMoreElements() && urls.nextElement().openConnection() != null\n        && Thread.currentThread().getContextClassLoader()\n            .getResources(\"META-INF/extra-orm.xml\").hasMoreElements()) {\n    throw new IllegalStateException(\"Duplicate mapping file on classpath\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run mvn dependency:tree and check for jars shipping the same resource path.","Use unique mapping file names in your own artifacts.","Exclude duplicate resources from third-party dependencies."],"tags":["quarkus","hibernate-orm","classpath","ambiguity"],"backgroundTag":"duplicate-classpath-resource","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}