hibernate/hibernate-orm · error · MappingException

Could not locate root element

Error message

Could not locate root element

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java:135

		staxFactory.setXMLResolver( xmlResourceResolver );
		return staxFactory;
	}

	protected StartElement seekRootElementStartEvent(XMLEventReader staxEventReader, Origin origin) {
		XMLEvent rootElementStartEvent;
		try {
			rootElementStartEvent = staxEventReader.peek();
			while ( rootElementStartEvent != null && !rootElementStartEvent.isStartElement() ) {
				staxEventReader.nextEvent();
				rootElementStartEvent = staxEventReader.peek();
			}
		}
		catch ( Exception e ) {
			throw new MappingException( "Error accessing StAX stream", e, origin );
		}

		if ( rootElementStartEvent == null ) {
			throw new MappingException( "Could not locate root element", origin );
		}

		return rootElementStartEvent.asStartElement();
	}

	protected abstract <X extends T> Binding<X> doBind(XMLEventReader staxEventReader, StartElement rootElementStartEvent, Origin origin);

	@SuppressWarnings("unused")
	protected static boolean hasNamespace(StartElement startElement) {
		return StringHelper.isNotEmpty( startElement.getName().getNamespaceURI() );
	}

	protected <X extends T> X jaxb(XMLEventReader reader, Schema xsd, JAXBContext jaxbContext, Origin origin) {
		final ContextProvidingValidationEventHandler handler = new ContextProvidingValidationEventHandler();

		try {
			final Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
			if ( isValidationEnabled() ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Open the file named in the Origin - it will have no root element
2. Add the required root (<hibernate-mapping> for hbm, <entity-mappings>/<hibernate-mappings> as appropriate)
3. If the file should be empty, stop passing it to the metadata sources at all
4. Fix the upstream generator that produced an empty output

Example fix

<!-- before: file content is empty or just a comment -->
<!-- mappings pending -->

<!-- after -->
<?xml version="1.0"?>
<hibernate-mapping>
    <class name="com.acme.User" table="users">...</class>
</hibernate-mapping>

// refuse empty/rootless documents before the binder sees them
try (var is = Files.newInputStream(path)) {
    var it = javax.xml.stream.XMLInputFactory.newInstance().createXMLEventReader(is);
    boolean hasRoot = false;
    while (it.hasNext()) { if (it.nextEvent().isStartElement()) { hasRoot = true; break; } }
    if (!hasRoot) throw new IllegalStateException(path + " has no root element");
}

try {
    binder.bind(stream, origin);
} catch (MappingException e) {
    if (e.getMessage().contains("Could not locate root element")) {
        // file is empty/comments-only: fix the generator or stop passing this file
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: Build pipelines emitting empty mapping files on failure; .hbm.xml or cfg.xml placeholders committed empty; text saved with .xml extension but no content.

Related errors

• Unknown type of binding : <bindingRoot>
• Unable to create StAX reader
• Error accessing StAX stream
• Unable to perform unmarshalling at line number {} and column
• Could not parse mapping document: %s (%s)

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/fb13baa1d7dc702d. Report an issue: GitHub.