{"record":{"id":"1fe758cbc6fbadec","repo":"quarkusio/quarkus","slug":"cannot-find-orm-mapping-file-mappingfilename","errorCode":null,"errorMessage":"Cannot find ORM mapping file '${mappingFileName}' in the classpath","messagePattern":"Cannot find ORM mapping file '(.+?)' in the classpath","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/JpaJandexScavenger.java","lineNumber":186,"sourceCode":"        }\n\n        // Classes explicitly mentioned in a mapping file\n        Set<String> mappingFileNames = new LinkedHashSet<>(persistenceUnitContribution.explicitlyListedMappingFiles);\n        if (!mappingFileNames.remove(XML_MAPPING_NO_FILE)) {\n            mappingFileNames.add(XML_MAPPING_DEFAULT_ORM_XML);\n        }\n        try (QuarkusMappingFileParser parser = QuarkusMappingFileParser.create()) {\n            for (String mappingFileName : mappingFileNames) {\n                hotDeploymentWatchedFiles.produce(new HotDeploymentWatchedFileBuildItem(mappingFileName));\n\n                Optional<RecordableXmlMapping> mappingOptional = parser.parse(persistenceUnitContribution.persistenceUnitName,\n                        persistenceUnitContribution.persistenceUnitRootURL, mappingFileName);\n                if (!mappingOptional.isPresent()) {\n                    if (persistenceUnitContribution.explicitlyListedMappingFiles.contains(mappingFileName)) {\n                        // Trigger an exception for files that are explicitly mentioned and could not be found\n                        // DEFAULT_ORM_XML in particular may be mentioned only implicitly,\n                        // in which case it's fine if we cannot find it.\n                        throw new IllegalStateException(\"Cannot find ORM mapping file '\" + mappingFileName\n                                + \"' in the classpath\");\n                    }\n                    continue;\n                }\n                RecordableXmlMapping mapping = mappingOptional.get();\n                if (mapping.getOrmXmlRoot() != null) {\n                    enlistOrmXmlMapping(collector, mapping.getOrmXmlRoot());\n                }\n                if (mapping.getHbmXmlRoot() != null) {\n                    enlistHbmXmlMapping(collector, mapping.getHbmXmlRoot());\n                }\n                collector.xmlMappingsByPU\n                        .computeIfAbsent(persistenceUnitContribution.persistenceUnitName, ignored -> new ArrayList<>())\n                        .add(mapping);\n            }\n        }\n    }\n","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/JpaJandexScavenger.java#L168-L204","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Correct the mapping-files config property or persistence.xml <mapping-file> entry to the actual path","If using quarkus.hibernate-orm.\"pu\".mapping-files, remove entries for files you don't actually have","Check build packaging/resource excludes aren't filtering the XML out of the jar"],"exampleFix":"// before (application.properties)\nquarkus.hibernate-orm.\"pu1\".mapping-files=orm/entites-orm.xml\n// after\nquarkus.hibernate-orm.\"pu1\".mapping-files=orm/entities-orm.xml","handlingStrategy":"validation","validationCode":"// In a test or startup check\nvar is = Thread.currentThread().getContextClassLoader()\n        .getResourceAsStream(\"META-INF/my-entities-orm.xml\");\nif (is == null) throw new IllegalStateException(\n    \"Mapping file META-INF/my-entities-orm.xml missing from classpath\");\ntry (is) { /* ok */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep mapping XML under src/main/resources/META-INF so it is always packaged","List every mapping file explicitly and verify paths in CI with a resource-existence test","After renaming/moving XML files, grep the config and persistence.xml for stale references"],"tags":["quarkus","hibernate-orm","classpath","mapping-file"],"backgroundTag":"classpath-resource-not-found","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"}