{"record":{"id":"1afbf7a667fdc828","repo":"quarkusio/quarkus","slug":"unsupported-mapping-file-root-unrecognized-type","errorCode":null,"errorMessage":"Unsupported mapping file root (unrecognized type): <root>","messagePattern":"Unsupported mapping file root \\(unrecognized type\\): <root>","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/xml/RecordableXmlMapping.java","lineNumber":34,"sourceCode":" * On contrary to Binding, this class can be serialized/deserialized by the BytecodeRecorder.\n */\npublic class RecordableXmlMapping {\n    // The following two properties are mutually exclusive: exactly one of them is non-null.\n    private final JaxbEntityMappingsImpl ormXmlRoot;\n    private final JaxbHbmHibernateMapping hbmXmlRoot;\n\n    private final SourceType originType;\n    private final String originName;\n\n    public static RecordableXmlMapping create(Binding<? extends JaxbBindableMappingDescriptor> binding) {\n        JaxbBindableMappingDescriptor root = binding.getRoot();\n        Origin origin = binding.getOrigin();\n        if (root instanceof JaxbEntityMappingsImpl) {\n            return new RecordableXmlMapping((JaxbEntityMappingsImpl) root, null, origin.getType(), origin.getName());\n        } else if (root instanceof JaxbHbmHibernateMapping) {\n            return new RecordableXmlMapping(null, (JaxbHbmHibernateMapping) root, origin.getType(), origin.getName());\n        } else {\n            throw new IllegalArgumentException(\"Unsupported mapping file root (unrecognized type): \" + root);\n        }\n    }\n\n    @RecordableConstructor\n    public RecordableXmlMapping(JaxbEntityMappingsImpl ormXmlRoot, JaxbHbmHibernateMapping hbmXmlRoot, SourceType originType,\n            String originName) {\n        this.ormXmlRoot = ormXmlRoot;\n        this.hbmXmlRoot = hbmXmlRoot;\n        this.originType = originType;\n        this.originName = originName;\n    }\n\n    @Override\n    public String toString() {\n        return \"RecordableXmlMapping{\" +\n                \"originName='\" + originName + '\\'' +\n                '}';\n    }","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/xml/RecordableXmlMapping.java#L16-L52","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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>.","Remove the file from quarkus.hibernate-orm.mapping-files / persistence.xml <mapping-file> entries if it is not a valid ORM mapping document.","Validate the XML against the corresponding XSD (orm.xsd / hibernate-mapping) to catch namespace or root-element mistakes.","If you added a custom JAXB root type, restructure it so Quarkus receives one of the two supported root types."],"exampleFix":"// before: mapping.xml has an unexpected root\n<mappings> ... </mappings>\n\n// after: valid ORM root\n<entity-mappings xmlns=\"https://jakarta.ee/xml/ns/persistence/orm\" version=\"3.0\"> ... </entity-mappings>","handlingStrategy":"validation","validationCode":"// Before registering a mapping file, verify its root element\nvar db = javax.xml.XMLConstants.W3C_XML_SCHEMA_NULL; // (use DOM parsing)\nvar doc = javax.xml.parsers.DocumentBuilderFactory.newInstance()\n        .newDocumentBuilder().parse(new File(\"META-INF/orm.xml\"));\nString root = doc.getDocumentElement().getLocalName();\nif (!(\"entity-mappings\".equals(root) || \"hibernate-mapping\".equals(root))) {\n    throw new IllegalArgumentException(\n        \"Unsupported mapping root '\" + root + \"': must be entity-mappings or hibernate-mapping\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = emfBuilder.build();\n} catch (IllegalArgumentException e) {\n    if (String.valueOf(e.getMessage()).startsWith(\"Unsupported mapping file root\")) {\n        throw new IllegalStateException(\"Check mapping file root element and namespaces\", e);\n    }\n    throw e;\n}","preventionTips":["Always use the official ORM XSD root <entity-mappings> with correct namespace for orm.xml files","Validate mapping XMLs against the XSD in CI before packaging","Only list actual Hibernate mapping documents in mapping-files config"],"tags":["hibernate-orm","xml-mapping","quarkus","bootstrap"],"backgroundTag":"unsupported-mapping-file-root","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"}