{"record":{"id":"bcc40459dc858cf9","repo":"quarkusio/quarkus","slug":"error-reading-mapping-file-mappingfilepath","errorCode":null,"errorMessage":"Error reading mapping file '<mappingFilePath>' ('<url>'): <e.getMessage()>","messagePattern":"Error reading mapping file '<mappingFilePath>' \\('<url>'\\): <e\\.getMessage\\(\\)>","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":69,"sourceCode":"     * @param persistenceUnitName The name of the persistence unit requesting the mapping file.\n     * @param persistenceUnitRootUrl The root URL of the persistence unit requesting the mapping file.\n     * @param mappingFilePath The path of the mapping file in the classpath.\n     * @return A summary of the parsed mapping file, or {@link Optional#empty()} if it was not found.\n     */\n    public Optional<RecordableXmlMapping> parse(String persistenceUnitName, URL persistenceUnitRootUrl,\n            String mappingFilePath) {\n        URL url = locateMappingFile(persistenceUnitName, persistenceUnitRootUrl, mappingFilePath);\n\n        if (url == null) {\n            // Ignore and let Hibernate ORM complain about it during bootstrap.\n            return Optional.empty();\n        }\n\n        try (InputStream stream = url.openStream()) {\n            Binding<? extends JaxbBindableMappingDescriptor> binding = binderAccess.bind(stream);\n            return Optional.of(RecordableXmlMapping.create(binding));\n        } catch (RuntimeException | IOException e) {\n            throw new IllegalStateException(\n                    \"Error reading mapping file '\" + mappingFilePath + \"' ('\" + url + \"'): \" + e.getMessage(), e);\n        }\n    }\n\n    private URL locateMappingFile(String persistenceUnitName, URL persistenceUnitRootUrl, String mappingFileName) {\n        List<URL> mappingFileURLs = FlatClassLoaderService.INSTANCE.locateResources(mappingFileName);\n        if (mappingFileURLs.isEmpty()) {\n            return null;\n        } else if (mappingFileURLs.size() == 1) {\n            return mappingFileURLs.get(0);\n        } else { // mappingFileURLs.size() > 1\n            // 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;","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/xml/QuarkusMappingFileParser.java#L51-L87","documentation":"QuarkusMappingFileParser throws this IllegalStateException when it located the ORM mapping file URL but fails to open or bind it. The underlying cause (IOException or runtime binding failure) is wrapped, and the message echoes the logical mapping file path and the resolved URL.","triggerScenarios":"In parse(), after locateMappingFile resolves a URL, url.openStream() throws IOException (unreadable/removed resource) or binderAccess.bind(stream) throws RuntimeException (malformed XML, schema violation).","commonSituations":"Malformed or XSD-invalid mapping XML; truncated file from an incomplete build; unreadable resource permissions; URL target disappeared between resolution and read.","solutions":["Open the URL from the message and fix the XML syntax/validation errors shown in the cause.","Rebuild the project to ensure the mapping file is completely and correctly packaged.","Check file permissions and resource readability at build time.","Confirm the document matches the expected Hibernate mapping XSD/root element."],"exampleFix":"<!-- before: malformed -->\n<entity-mappings><entity class=\"Foo\"></entity-mappings>\n<!-- after: well-formed, schema-valid -->\n<entity-mappings xmlns=\"https://jakarta.ee/xml/ns/persistence/orm\" version=\"3.0\">\n  <entity class=\"com.example.Foo\"/>\n</entity-mappings>","handlingStrategy":"try-catch","validationCode":"URL url = locateMappingFile(name, root, mappingFile);\ntry (InputStream is = url.openStream()) {\n    if (is.read() == -1) throw new IllegalStateException(\"Mapping file is empty: \" + url);\n}","typeGuard":null,"tryCatchPattern":"try {\n    parseMapping(mappingFile);\n} catch (IllegalStateException e) {\n    log.error(\"Mapping file unreadable/invalid: \" + e.getMessage(), e.getCause());\n    throw new DeploymentException(\"Fix mapping XML before build\", e);\n}","preventionTips":["Validate mapping XML against the Hibernate XSD in CI.","Keep mapping files fully packaged and committed to src/main/resources.","Check the wrapped cause for the precise IO or parse failure."],"tags":["quarkus","hibernate-orm","xml","parsing"],"backgroundTag":"mapping-file-parse-error","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}