hibernate/hibernate-orm · error · MappingException

Error accessing StAX stream

Error message

Error accessing StAX stream

What it means

While skipping over prolog content (comments, whitespace, processing instructions) hunting for the root start element in seekRootElementStartEvent, peek()/nextEvent() threw. Any exception there is wrapped in a MappingException 'Error accessing StAX stream' with the Origin. The stream broke or ended abnormally mid-scan rather than at open time.

Source

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

	}

	private XMLInputFactory buildStaxFactory() {
		XMLInputFactory staxFactory = XMLInputFactory.newInstance();
		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();

View on GitHub (pinned to fad1729dce)

Solutions

  1. Read the cause - it usually contains the underlying message ('Premature end of file', 'stream closed')
  2. Open the file named by the Origin and check it is complete (compare size, re-save from source)
  3. Ensure no other code closes or wraps the same stream during binding
  4. Lint the file with any XML validator to confirm the prolog is intact

Example fix

<!-- before: truncated prolog -->
<?xml version="1.0"?>
<!-- TODO finish this mapp

<!-- after -->
<?xml version="1.0"?>
<!-- attachment mappings -->
<hibernate-mapping>...</hibernate-mapping>
Defensive patterns

Strategy: validation

Validate before calling

// cheap sanity check: file exists, non-empty, and starts with '<' after BOM
byte[] head = Files.readAllBytes(path);
String s = new String(head, java.nio.charset.StandardCharsets.UTF_8).trim();
if (head.length == 0 || !s.startsWith("<")) {
    throw new IllegalStateException(path + " does not look like readable XML");
}

Try / catch

try {
    binder.bind(stream, origin);
} catch (MappingException e) {
    if (e.getMessage().contains("Error accessing StAX stream")) {
        // underlying stream broke mid-read: re-check file completeness, no concurrent closes
    }
    throw e;
}

Prevention

When it happens

Trigger: A mapping document truncated in the middle of its prolog or DTD, a stream closed by another thread, or an I/O error surfacing lazily while the reader pulls events before the root element.

Common situations: Partial uploads or interrupted writes producing truncated XML files; concurrent code closing shared streams; files consisting of a very long comment/doctype then EOF.

Related errors

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