quarkusio/quarkus · error · IllegalStateException

Cannot find ORM mapping file '${mappingFileName}' in the cla

Error message

Cannot find ORM mapping file '${mappingFileName}' in the classpath

What it means

Quarkus's JPA/Hibernate ORM deployment scanner (JpaJandexScavenger) collects mapping files (orm.xml) listed by a persistence unit. When a mapping file name cannot be resolved on the classpath AND it was explicitly listed for the persistence unit, it throws IllegalStateException because the user referenced a file that does not exist. Implicitly mentioned files (e.g. META-INF/orm.xml when absent) are silently skipped instead.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/JpaJandexScavenger.java:186

        }

        // Classes explicitly mentioned in a mapping file
        Set<String> mappingFileNames = new LinkedHashSet<>(persistenceUnitContribution.explicitlyListedMappingFiles);
        if (!mappingFileNames.remove(XML_MAPPING_NO_FILE)) {
            mappingFileNames.add(XML_MAPPING_DEFAULT_ORM_XML);
        }
        try (QuarkusMappingFileParser parser = QuarkusMappingFileParser.create()) {
            for (String mappingFileName : mappingFileNames) {
                hotDeploymentWatchedFiles.produce(new HotDeploymentWatchedFileBuildItem(mappingFileName));

                Optional<RecordableXmlMapping> mappingOptional = parser.parse(persistenceUnitContribution.persistenceUnitName,
                        persistenceUnitContribution.persistenceUnitRootURL, mappingFileName);
                if (!mappingOptional.isPresent()) {
                    if (persistenceUnitContribution.explicitlyListedMappingFiles.contains(mappingFileName)) {
                        // Trigger an exception for files that are explicitly mentioned and could not be found
                        // DEFAULT_ORM_XML in particular may be mentioned only implicitly,
                        // in which case it's fine if we cannot find it.
                        throw new IllegalStateException("Cannot find ORM mapping file '" + mappingFileName
                                + "' in the classpath");
                    }
                    continue;
                }
                RecordableXmlMapping mapping = mappingOptional.get();
                if (mapping.getOrmXmlRoot() != null) {
                    enlistOrmXmlMapping(collector, mapping.getOrmXmlRoot());
                }
                if (mapping.getHbmXmlRoot() != null) {
                    enlistHbmXmlMapping(collector, mapping.getHbmXmlRoot());
                }
                collector.xmlMappingsByPU
                        .computeIfAbsent(persistenceUnitContribution.persistenceUnitName, ignored -> new ArrayList<>())
                        .add(mapping);
            }
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the mapping file exists at the exact classpath-relative path (e.g. src/main/resources/META-INF/my-orm.xml) and the listed name matches
2. Correct the mapping-files config property or persistence.xml <mapping-file> entry to the actual path
3. If using quarkus.hibernate-orm."pu".mapping-files, remove entries for files you don't actually have
4. Check build packaging/resource excludes aren't filtering the XML out of the jar

Example fix

// before (application.properties)
quarkus.hibernate-orm."pu1".mapping-files=orm/entites-orm.xml
// after
quarkus.hibernate-orm."pu1".mapping-files=orm/entities-orm.xml

// In a test or startup check
var is = Thread.currentThread().getContextClassLoader()
        .getResourceAsStream("META-INF/my-entities-orm.xml");
if (is == null) throw new IllegalStateException(
    "Mapping file META-INF/my-entities-orm.xml missing from classpath");
try (is) { /* ok */ }

When it happens

Trigger: A persistence unit (via persistence.xml <mapping-file> or quarkus.hibernate-orm."pu".mapping-files config) references a mapping file path that is not present in the application archive/classpath.

Common situations: Typo in the mapping-file path; orm.xml placed outside META-INF; file excluded by build packaging config; renaming/moving the resource without updating persistence.xml; multi-module setup where the resource lives in another module not on the classpath.

Related errors

• Persistence unit '<persistenceUnitName>' references mapping
• Failed to load CodeGenProvider class from deployment classlo
• Failed to read %s
• Failed to read resources from classpath
• Failed to open class path file <file>

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