hibernate/hibernate-orm · error · XMLStreamException

Unexpected event type '{}' encountered. Found event: {}

Error message

Unexpected event type '{}' encountered. Found event: {}

What it means

While JAXB-binding a mapping document, BaseXMLEventReader collects the text of an element: it folds CHARACTERS and ENTITY_REFERENCE into the buffer, ignores COMMENT and PROCESSING_INSTRUCTION, and throws XMLStreamException for any other StAX event type. The message names the offending event type and includes the Location (line/column) so the construct can be found in the document.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/stax/BaseXMLEventReader.java:93

				case XMLStreamConstants.SPACE:
				case XMLStreamConstants.CDATA: {
					final Characters characters = event.asCharacters();
					text.append(characters.getData());
					break;
				}
				case XMLStreamConstants.ENTITY_REFERENCE: {
					final EntityReference entityReference = (EntityReference)event;
					final EntityDeclaration declaration = entityReference.getDeclaration();
					text.append(declaration.getReplacementText());
					break;
				}
				case XMLStreamConstants.COMMENT:
				case XMLStreamConstants.PROCESSING_INSTRUCTION: {
					//Ignore
					break;
				}
				default: {
					throw new XMLStreamException("Unexpected event type '" + XMLStreamConstantsUtils.getEventName(event.getEventType()) + "' encountered. Found event: " + event, event.getLocation());
				}
			}

			event = this.nextEvent();
		}

		return text.toString();
	}

	@Override
	public final XMLEvent nextTag() throws XMLStreamException {
		XMLEvent event = this.nextEvent();
		while ((event.isCharacters() && event.asCharacters().isWhiteSpace())
				|| event.isProcessingInstruction()
				|| event.getEventType() == XMLStreamConstants.COMMENT) {

			event = this.nextEvent();
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Reproduce with a stock parser: xmllint --noout mapping.hbm.xml, or parse with DocumentBuilderFactory to confirm well-formedness and event structure
2. Remove DOCTYPE/DTD constructs or move them to the document prolog where the schema expects them
3. Align on one StAX implementation: run dependency:tree and exclude extra/duplicate woodstox or stax artifacts so the JDK or a single woodstox version serves
4. Validate the document against Hibernate's bundled XSD before passing it to Hibernate

DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.setNamespaceAware(true);
try {
    f.newDocumentBuilder().parse(new File("item.hbm.xml")); // pre-flight well-formedness
} catch (org.xml.sax.SAXException e) {
    throw new IllegalStateException("mapping file not well-formed: " + e.getMessage(), e);
}

catch (javax.xml.stream.XMLStreamException e) {
    // e.getLocation() carries line/column; surface it with the file name
    throw new IllegalStateException("Unexpected XML construct at line " + e.getLocation().getLineNumber(), e);
}

When it happens

Trigger: A mapping document whose event stream yields an event that is neither text, entity, comment, nor PI while reading element content — e.g. a DOCTYPE/DTD event or a nested start-element appearing where text is expected, or a non-standard StAX implementation (mismatched Woodstox version) splitting the event stream differently than Hibernate's reader wrappers expect.

Common situations: Hand-edited hbm.xml with a DTD/DOCTYPE in an unexpected position; multiple StAX providers (woodstox vs JDK) on the classpath in app servers, with an older woodstox winning; XML pre-processed by homegrown filters that drop or reorder events.

Related errors

• Unable to create StAX reader
• Error accessing StAX stream
• Could not parse mapping document: %s (%s)
• Multiple active MetadataBuilder definitions were discovered
• Unable to check validity of passed ValidatorFactory

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