quarkusio/quarkus · error · IllegalArgumentException

Unsupported mapping file root (unrecognized type): <root>

Error message

Unsupported mapping file root (unrecognized type): <root>

What it means

Quarkus records XML mapping files (orm.xml / .hbm.xml) for the Hibernate ORM build process in RecordableXmlMapping.create(). The root element of the parsed mapping file must be either a JaxbEntityMappingsImpl (entity-mappings) or a JaxbHbmHibernateMapping (hibernate-mapping). Any other root element type throws this IllegalArgumentException because Quarkus cannot represent it.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/xml/RecordableXmlMapping.java:34

 * On contrary to Binding, this class can be serialized/deserialized by the BytecodeRecorder.
 */
public class RecordableXmlMapping {
    // The following two properties are mutually exclusive: exactly one of them is non-null.
    private final JaxbEntityMappingsImpl ormXmlRoot;
    private final JaxbHbmHibernateMapping hbmXmlRoot;

    private final SourceType originType;
    private final String originName;

    public static RecordableXmlMapping create(Binding<? extends JaxbBindableMappingDescriptor> binding) {
        JaxbBindableMappingDescriptor root = binding.getRoot();
        Origin origin = binding.getOrigin();
        if (root instanceof JaxbEntityMappingsImpl) {
            return new RecordableXmlMapping((JaxbEntityMappingsImpl) root, null, origin.getType(), origin.getName());
        } else if (root instanceof JaxbHbmHibernateMapping) {
            return new RecordableXmlMapping(null, (JaxbHbmHibernateMapping) root, origin.getType(), origin.getName());
        } else {
            throw new IllegalArgumentException("Unsupported mapping file root (unrecognized type): " + root);
        }
    }

    @RecordableConstructor
    public RecordableXmlMapping(JaxbEntityMappingsImpl ormXmlRoot, JaxbHbmHibernateMapping hbmXmlRoot, SourceType originType,
            String originName) {
        this.ormXmlRoot = ormXmlRoot;
        this.hbmXmlRoot = hbmXmlRoot;
        this.originType = originType;
        this.originName = originName;
    }

    @Override
    public String toString() {
        return "RecordableXmlMapping{" +
                "originName='" + originName + '\'' +
                '}';
    }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Open the mapping XML file referenced in your persistence unit and make sure its root element is <entity-mappings> (with the correct ORM XSD namespace) or <hibernate-mapping>.
  2. Remove the file from quarkus.hibernate-orm.mapping-files / persistence.xml <mapping-file> entries if it is not a valid ORM mapping document.
  3. Validate the XML against the corresponding XSD (orm.xsd / hibernate-mapping) to catch namespace or root-element mistakes.
  4. If you added a custom JAXB root type, restructure it so Quarkus receives one of the two supported root types.

Example fix

// before: mapping.xml has an unexpected root
<mappings> ... </mappings>

// after: valid ORM root
<entity-mappings xmlns="https://jakarta.ee/xml/ns/persistence/orm" version="3.0"> ... </entity-mappings>
Defensive patterns

Strategy: validation

Validate before calling

// Before registering a mapping file, verify its root element
var db = javax.xml.XMLConstants.W3C_XML_SCHEMA_NULL; // (use DOM parsing)
var doc = javax.xml.parsers.DocumentBuilderFactory.newInstance()
        .newDocumentBuilder().parse(new File("META-INF/orm.xml"));
String root = doc.getDocumentElement().getLocalName();
if (!("entity-mappings".equals(root) || "hibernate-mapping".equals(root))) {
    throw new IllegalArgumentException(
        "Unsupported mapping root '" + root + "': must be entity-mappings or hibernate-mapping");
}

Try / catch

try {
    sessionFactory = emfBuilder.build();
} catch (IllegalArgumentException e) {
    if (String.valueOf(e.getMessage()).startsWith("Unsupported mapping file root")) {
        throw new IllegalStateException("Check mapping file root element and namespaces", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling RecordableXmlMapping.create(binding) with a JaxbBinding whose root object is neither JaxbEntityMappingsImpl nor JaxbHbmHibernateMapping — i.e. an XML mapping file whose root element is not <entity-mappings> or <hibernate-mapping>, or is an unmarshalled type Quarkus doesn't recognize.

Common situations: A mapping XML file with a malformed or wrong root tag (typo, wrong namespace), an XML file registered as a mapping that is actually a different kind of descriptor, or a Hibernate ORM version change that altered the JAXB root classes.

Related errors

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