{"record":{"id":"fb13baa1d7dc702d","repo":"hibernate/hibernate-orm","slug":"could-not-locate-root-element-fb13ba","errorCode":null,"errorMessage":"Could not locate root element","messagePattern":"Could not locate root element","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java","lineNumber":135,"sourceCode":"\t\tstaxFactory.setXMLResolver( xmlResourceResolver );\n\t\treturn staxFactory;\n\t}\n\n\tprotected StartElement seekRootElementStartEvent(XMLEventReader staxEventReader, Origin origin) {\n\t\tXMLEvent rootElementStartEvent;\n\t\ttry {\n\t\t\trootElementStartEvent = staxEventReader.peek();\n\t\t\twhile ( rootElementStartEvent != null && !rootElementStartEvent.isStartElement() ) {\n\t\t\t\tstaxEventReader.nextEvent();\n\t\t\t\trootElementStartEvent = staxEventReader.peek();\n\t\t\t}\n\t\t}\n\t\tcatch ( Exception e ) {\n\t\t\tthrow new MappingException( \"Error accessing StAX stream\", e, origin );\n\t\t}\n\n\t\tif ( rootElementStartEvent == null ) {\n\t\t\tthrow new MappingException( \"Could not locate root element\", origin );\n\t\t}\n\n\t\treturn rootElementStartEvent.asStartElement();\n\t}\n\n\tprotected abstract <X extends T> Binding<X> doBind(XMLEventReader staxEventReader, StartElement rootElementStartEvent, Origin origin);\n\n\t@SuppressWarnings(\"unused\")\n\tprotected static boolean hasNamespace(StartElement startElement) {\n\t\treturn StringHelper.isNotEmpty( startElement.getName().getNamespaceURI() );\n\t}\n\n\tprotected <X extends T> X jaxb(XMLEventReader reader, Schema xsd, JAXBContext jaxbContext, Origin origin) {\n\t\tfinal ContextProvidingValidationEventHandler handler = new ContextProvidingValidationEventHandler();\n\n\t\ttry {\n\t\t\tfinal Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();\n\t\t\tif ( isValidationEnabled() ) {","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java#L117-L153","documentation":"seekRootElementStartEvent walked the entire event stream without ever finding a start element - peek() returned null. The document contains no root element at all: it is empty, whitespace-only, or made up solely of comments/processing instructions. Thrown as MappingException with the Origin.","triggerScenarios":"Binding a zero-byte mapping file, a file containing only a comment or whitespace, or an empty filtered/failed generator output passed to the binder.","commonSituations":"Build pipelines emitting empty mapping files on failure; .hbm.xml or cfg.xml placeholders committed empty; text saved with .xml extension but no content.","solutions":["Open the file named in the Origin - it will have no root element","Add the required root (<hibernate-mapping> for hbm, <entity-mappings>/<hibernate-mappings> as appropriate)","If the file should be empty, stop passing it to the metadata sources at all","Fix the upstream generator that produced an empty output"],"exampleFix":"<!-- before: file content is empty or just a comment -->\n<!-- mappings pending -->\n\n<!-- after -->\n<?xml version=\"1.0\"?>\n<hibernate-mapping>\n    <class name=\"com.acme.User\" table=\"users\">...</class>\n</hibernate-mapping>","handlingStrategy":"validation","validationCode":"// refuse empty/rootless documents before the binder sees them\ntry (var is = Files.newInputStream(path)) {\n    var it = javax.xml.stream.XMLInputFactory.newInstance().createXMLEventReader(is);\n    boolean hasRoot = false;\n    while (it.hasNext()) { if (it.nextEvent().isStartElement()) { hasRoot = true; break; } }\n    if (!hasRoot) throw new IllegalStateException(path + \" has no root element\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    binder.bind(stream, origin);\n} catch (MappingException e) {\n    if (e.getMessage().contains(\"Could not locate root element\")) {\n        // file is empty/comments-only: fix the generator or stop passing this file\n    }\n    throw e;\n}","preventionTips":["Make code generators fail loudly instead of emitting empty XML files","Add a CI check that every committed *.hbm.xml/*.xml mapping has a root element","Do not register placeholder/empty files as mapping sources"],"tags":["hibernate","jaxb","xml","empty-file","bootstrap"],"backgroundTag":"empty-xml-document","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}