hibernate/hibernate-orm · error · MappingException

Unable to create StAX reader

Error message

Unable to create StAX reader

What it means

AbstractBinder.createReader fails to build a StAX XMLEventReader over an InputStream: XMLStreamFactory.createXMLEventReader threw XMLStreamException, wrapped in a MappingException with the Origin. The XML could not be handed to a parser at all - typically malformed content, an unsupported/lying encoding declaration, or an already-consumed/closed stream.

Source

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

		finally {
			try {
				eventReader.close();
			}
			catch (XMLStreamException e) {
				JAXB_LOGGER.unableToCloseStaxReader( e );
			}
		}
	}

	protected XMLEventReader createReader(InputStream stream, Origin origin) {
		try {
			// create a standard StAX reader
			final XMLEventReader staxReader = staxFactory().createXMLEventReader( stream );
			// and wrap it in a buffered reader (keeping 100 element sized buffer)
			return new BufferedXMLEventReader( staxReader, 100 );
		}
		catch ( XMLStreamException e ) {
			throw new MappingException( "Unable to create StAX reader", e, origin );
		}
	}

	@Override
	public <X extends T> Binding<X> bind(Source source, Origin origin) {
		final XMLEventReader eventReader = createReader( source, origin );
		return doBind( eventReader, origin );
	}

	protected XMLEventReader createReader(Source source, Origin origin) {
		try {
			// create a standard StAX reader
			final XMLEventReader staxReader = staxFactory().createXMLEventReader( source );
			// and wrap it in a buffered reader (keeping 100 element sized buffer)
			return new BufferedXMLEventReader( staxReader, 100 );
		}
		catch ( XMLStreamException e ) {
			throw new MappingException( "Unable to create StAX reader", e, origin );

View on GitHub (pinned to fad1729dce)

Solutions

  1. Check the cause chain - XMLStreamException names the byte/line where parsing broke
  2. Ensure the stream is fresh and readable when handed to the binder (do not pre-read it)
  3. Verify the file is well-formed XML and its declared encoding matches actual bytes (open in an editor that shows encoding)
  4. Remove or align conflicting StAX/JAXP dependencies (keep one StAX impl)
  5. Test with a minimal known-good mapping file to isolate content vs classpath issues

Example fix

// before: stream already consumed
InputStream in = ...;
byte[] head = in.readNBytes(100); // sniffing consumed the stream
binder.bind(in, origin); // -> Unable to create StAX reader

// after: re-open a fresh stream
binder.bind(Files.newInputStream(path), origin);
Defensive patterns

Strategy: validation

Validate before calling

// verify the XML is consumable before handing the stream to the binder
try (InputStream probe = new BufferedInputStream(Files.newInputStream(path))) {
    javax.xml.parsers.DocumentBuilderFactory.newInstance()
        .newDocumentBuilder().parse(probe); // throws early with a precise position
}

Try / catch

try {
    binder.bind(stream, origin);
} catch (MappingException e) {
    if (e.getCause() instanceof javax.xml.stream.XMLStreamException) {
        // fix the XML at the reported offset or re-open a fresh stream
    }
    throw e;
}

Prevention

When it happens

Trigger: Passing a mapping InputStream that is empty after prior consumption, contains invalid XML syntax in the prolog, declares an encoding that does not match the bytes, or when a broken StAX provider is on the classpath.

Common situations: Streams read twice (once for sniffing, once for binding); files saved with wrong encoding (UTF-16 declaration on UTF-8 bytes); classpath conflicts swapping in a different StAX implementation (woodstox vs JDK).

Related errors

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