{"record":{"id":"1e95dfab586ab5bf","repo":"hibernate/hibernate-orm","slug":"unexpected-event-type-encountered-found-even","errorCode":null,"errorMessage":"Unexpected event type '{}' encountered. Found event: {}","messagePattern":"Unexpected event type '(.+?)' encountered\\. Found event: (.+?)","errorType":"exception","errorClass":"XMLStreamException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/stax/BaseXMLEventReader.java","lineNumber":93,"sourceCode":"\t\t\t\tcase XMLStreamConstants.SPACE:\n\t\t\t\tcase XMLStreamConstants.CDATA: {\n\t\t\t\t\tfinal Characters characters = event.asCharacters();\n\t\t\t\t\ttext.append(characters.getData());\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase XMLStreamConstants.ENTITY_REFERENCE: {\n\t\t\t\t\tfinal EntityReference entityReference = (EntityReference)event;\n\t\t\t\t\tfinal EntityDeclaration declaration = entityReference.getDeclaration();\n\t\t\t\t\ttext.append(declaration.getReplacementText());\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase XMLStreamConstants.COMMENT:\n\t\t\t\tcase XMLStreamConstants.PROCESSING_INSTRUCTION: {\n\t\t\t\t\t//Ignore\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tdefault: {\n\t\t\t\t\tthrow new XMLStreamException(\"Unexpected event type '\" + XMLStreamConstantsUtils.getEventName(event.getEventType()) + \"' encountered. Found event: \" + event, event.getLocation());\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tevent = this.nextEvent();\n\t\t}\n\n\t\treturn text.toString();\n\t}\n\n\t@Override\n\tpublic final XMLEvent nextTag() throws XMLStreamException {\n\t\tXMLEvent event = this.nextEvent();\n\t\twhile ((event.isCharacters() && event.asCharacters().isWhiteSpace())\n\t\t\t\t|| event.isProcessingInstruction()\n\t\t\t\t|| event.getEventType() == XMLStreamConstants.COMMENT) {\n\n\t\t\tevent = this.nextEvent();\n\t\t}","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/stax/BaseXMLEventReader.java#L75-L111","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reproduce with a stock parser: xmllint --noout mapping.hbm.xml, or parse with DocumentBuilderFactory to confirm well-formedness and event structure","Remove DOCTYPE/DTD constructs or move them to the document prolog where the schema expects them","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","Validate the document against Hibernate's bundled XSD before passing it to Hibernate"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();\nf.setNamespaceAware(true);\ntry {\n    f.newDocumentBuilder().parse(new File(\"item.hbm.xml\")); // pre-flight well-formedness\n} catch (org.xml.sax.SAXException e) {\n    throw new IllegalStateException(\"mapping file not well-formed: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"catch (javax.xml.stream.XMLStreamException e) {\n    // e.getLocation() carries line/column; surface it with the file name\n    throw new IllegalStateException(\"Unexpected XML construct at line \" + e.getLocation().getLineNumber(), e);\n}","preventionTips":["Keep exactly one StAX implementation on the classpath (audit for duplicate woodstox/stax jars)","Never hand-insert DOCTYPE/DTD into mapping element content","Validate every mapping file against Hibernate's bundled XSD in the build"],"tags":["stax","xml-parsing","mapping-file","dependency-conflict"],"backgroundTag":"stax-unexpected-event","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}