quarkusio/quarkus · error · IllegalStateException

Persistence unit '<persistenceUnitName>' references mapping

Error message

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>

What it means

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.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/xml/QuarkusMappingFileParser.java:99

            // Multiple classpath resources match this name.
            // We need to resolve the ambiguity.
            URL urlInSameMappingFile = null;
            if (persistenceUnitRootUrl != null) {
                for (URL url : mappingFileURLs) {
                    if (!persistenceUnitRootUrl.equals(ArchiveHelper.getJarURLFromURLEntry(url, mappingFileName))) {
                        continue;
                    }
                    if (urlInSameMappingFile == null) {
                        urlInSameMappingFile = url;
                    } else {
                        // Multiple matches in the same JAR...? Can this even happen?
                        urlInSameMappingFile = null;
                        break;
                    }
                }
            }
            if (urlInSameMappingFile == null) {
                throw new IllegalStateException("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);
            }
            return urlInSameMappingFile;
        }
    }

    private static BootstrapServiceRegistry createEmptyBootstrapServiceRegistry() {
        final ClassLoaderService providedClassLoaderService = FlatClassLoaderService.INSTANCE;
        // N.B. support for integrators removed
        final IntegratorService integratorService = new IntegratorService() {
            @Override
            public Iterable<Integrator> getIntegrators() {
                return Collections.emptyList();
            }
        };
        final StrategySelector strategySelector = QuarkusStrategySelectorBuilder.buildSelector(providedClassLoaderService);

View on GitHub (pinned to e1c734241f)

Solutions

1. Exclude the duplicate resource from one dependency (Maven exclusion or resource filtering).
2. Rename your mapping file so its path is unique on the classpath.
3. Remove the stale/duplicate jar so only one resource with that path remains.
4. Keep the mapping file under the persistence unit root so Quarkus can disambiguate it.

Example fix

<!-- before: two jars contain META-INF/extra-orm.xml -->
<!-- after (pom.xml): exclude the conflicting dependency resource -->
<exclusion>
  <groupId>com.example</groupId>
  <artifactId>duplicate-mappings-lib</artifactId>
</exclusion>

Enumeration<URL> urls = Thread.currentThread().getContextClassLoader()
    .getResources("META-INF/extra-orm.xml");
if (urls.hasMoreElements() && urls.nextElement().openConnection() != null
        && Thread.currentThread().getContextClassLoader()
            .getResources("META-INF/extra-orm.xml").hasMoreElements()) {
    throw new IllegalStateException("Duplicate mapping file on classpath");
}

When it happens

Trigger: locateMappingFile finds several URLs via FlatClassLoaderService.locateResources(mappingFileName); the fallback disambiguation by persistence unit root fails (urlInSameMappingFile == null) and it throws.

Common situations: 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.

Related errors

• Cannot find ORM mapping file '${mappingFileName}' in the cla
• No name provided and multiple persistence units found
• Failed to load CodeGenProvider class from deployment classlo
• Failed to read %s
• Failed to read resources from classpath

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/ebb09a6195b3727d. Report an issue: GitHub.