{"record":{"id":"52ae89e6e7207210","repo":"hibernate/hibernate-orm","slug":"unable-to-create-stax-reader-52ae89","errorCode":null,"errorMessage":"Unable to create StAX reader","messagePattern":"Unable to create StAX reader","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java","lineNumber":69,"sourceCode":"\t\tfinally {\n\t\t\ttry {\n\t\t\t\teventReader.close();\n\t\t\t}\n\t\t\tcatch (XMLStreamException e) {\n\t\t\t\tJAXB_LOGGER.unableToCloseStaxReader( e );\n\t\t\t}\n\t\t}\n\t}\n\n\tprotected XMLEventReader createReader(InputStream stream, Origin origin) {\n\t\ttry {\n\t\t\t// create a standard StAX reader\n\t\t\tfinal XMLEventReader staxReader = staxFactory().createXMLEventReader( stream );\n\t\t\t// and wrap it in a buffered reader (keeping 100 element sized buffer)\n\t\t\treturn new BufferedXMLEventReader( staxReader, 100 );\n\t\t}\n\t\tcatch ( XMLStreamException e ) {\n\t\t\tthrow new MappingException( \"Unable to create StAX reader\", e, origin );\n\t\t}\n\t}\n\n\t@Override\n\tpublic <X extends T> Binding<X> bind(Source source, Origin origin) {\n\t\tfinal XMLEventReader eventReader = createReader( source, origin );\n\t\treturn doBind( eventReader, origin );\n\t}\n\n\tprotected XMLEventReader createReader(Source source, Origin origin) {\n\t\ttry {\n\t\t\t// create a standard StAX reader\n\t\t\tfinal XMLEventReader staxReader = staxFactory().createXMLEventReader( source );\n\t\t\t// and wrap it in a buffered reader (keeping 100 element sized buffer)\n\t\t\treturn new BufferedXMLEventReader( staxReader, 100 );\n\t\t}\n\t\tcatch ( XMLStreamException e ) {\n\t\t\tthrow new MappingException( \"Unable to create StAX reader\", e, origin );","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Check the cause chain - XMLStreamException names the byte/line where parsing broke","Ensure the stream is fresh and readable when handed to the binder (do not pre-read it)","Verify the file is well-formed XML and its declared encoding matches actual bytes (open in an editor that shows encoding)","Remove or align conflicting StAX/JAXP dependencies (keep one StAX impl)","Test with a minimal known-good mapping file to isolate content vs classpath issues"],"exampleFix":"// before: stream already consumed\nInputStream in = ...;\nbyte[] head = in.readNBytes(100); // sniffing consumed the stream\nbinder.bind(in, origin); // -> Unable to create StAX reader\n\n// after: re-open a fresh stream\nbinder.bind(Files.newInputStream(path), origin);","handlingStrategy":"validation","validationCode":"// verify the XML is consumable before handing the stream to the binder\ntry (InputStream probe = new BufferedInputStream(Files.newInputStream(path))) {\n    javax.xml.parsers.DocumentBuilderFactory.newInstance()\n        .newDocumentBuilder().parse(probe); // throws early with a precise position\n}","typeGuard":null,"tryCatchPattern":"try {\n    binder.bind(stream, origin);\n} catch (MappingException e) {\n    if (e.getCause() instanceof javax.xml.stream.XMLStreamException) {\n        // fix the XML at the reported offset or re-open a fresh stream\n    }\n    throw e;\n}","preventionTips":["Never hand the binder a stream you have already read from","Open a fresh stream per bind attempt","Keep exactly one StAX implementation on the classpath"],"tags":["hibernate","jaxb","stax","xml-parsing","bootstrap"],"backgroundTag":"stax-parser-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}