quarkusio/quarkus · error · IllegalStateException

Error reading mapping file '<mappingFilePath>' ('<url>'): <e

Error message

Error reading mapping file '<mappingFilePath>' ('<url>'): <e.getMessage()>

What it means

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.

Source

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

     * @param persistenceUnitName The name of the persistence unit requesting the mapping file.
     * @param persistenceUnitRootUrl The root URL of the persistence unit requesting the mapping file.
     * @param mappingFilePath The path of the mapping file in the classpath.
     * @return A summary of the parsed mapping file, or {@link Optional#empty()} if it was not found.
     */
    public Optional<RecordableXmlMapping> parse(String persistenceUnitName, URL persistenceUnitRootUrl,
            String mappingFilePath) {
        URL url = locateMappingFile(persistenceUnitName, persistenceUnitRootUrl, mappingFilePath);

        if (url == null) {
            // Ignore and let Hibernate ORM complain about it during bootstrap.
            return Optional.empty();
        }

        try (InputStream stream = url.openStream()) {
            Binding<? extends JaxbBindableMappingDescriptor> binding = binderAccess.bind(stream);
            return Optional.of(RecordableXmlMapping.create(binding));
        } catch (RuntimeException | IOException e) {
            throw new IllegalStateException(
                    "Error reading mapping file '" + mappingFilePath + "' ('" + url + "'): " + e.getMessage(), e);
        }
    }

    private URL locateMappingFile(String persistenceUnitName, URL persistenceUnitRootUrl, String mappingFileName) {
        List<URL> mappingFileURLs = FlatClassLoaderService.INSTANCE.locateResources(mappingFileName);
        if (mappingFileURLs.isEmpty()) {
            return null;
        } else if (mappingFileURLs.size() == 1) {
            return mappingFileURLs.get(0);
        } else { // mappingFileURLs.size() > 1
            // 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;

View on GitHub (pinned to e1c734241f)

Solutions

1. Open the URL from the message and fix the XML syntax/validation errors shown in the cause.
2. Rebuild the project to ensure the mapping file is completely and correctly packaged.
3. Check file permissions and resource readability at build time.
4. Confirm the document matches the expected Hibernate mapping XSD/root element.

Example fix

<!-- before: malformed -->
<entity-mappings><entity class="Foo"></entity-mappings>
<!-- after: well-formed, schema-valid -->
<entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm" version="3.0">
  <entity class="com.example.Foo"/>
</entity-mappings>

URL url = locateMappingFile(name, root, mappingFile);
try (InputStream is = url.openStream()) {
    if (is.read() == -1) throw new IllegalStateException("Mapping file is empty: " + url);
}

try {
    parseMapping(mappingFile);
} catch (IllegalStateException e) {
    log.error("Mapping file unreadable/invalid: " + e.getMessage(), e.getCause());
    throw new DeploymentException("Fix mapping XML before build", e);
}

When it happens

Trigger: In parse(), after locateMappingFile resolves a URL, url.openStream() throws IOException (unreadable/removed resource) or binderAccess.bind(stream) throws RuntimeException (malformed XML, schema violation).

Common situations: Malformed or XSD-invalid mapping XML; truncated file from an incomplete build; unreadable resource permissions; URL target disappeared between resolution and read.

Related errors

• Cannot find ORM mapping file '${mappingFileName}' in the cla
• Missing attribute '${nodeName}.class'
• Annotation ${dotName} was not expected on a target of kind $
• Type ${className} must be annotated with @Embeddable, becaus
• Multiple ${AdditionalPersistenceUnitBuildItem} for persisten

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