{"record":{"id":"2566cae15cf0022e","repo":"hibernate/hibernate-orm","slug":"error-accessing-stax-stream-2566ca","errorCode":null,"errorMessage":"Error accessing StAX stream","messagePattern":"Error accessing StAX stream","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java","lineNumber":131,"sourceCode":"\t}\n\n\tprivate XMLInputFactory buildStaxFactory() {\n\t\tXMLInputFactory staxFactory = XMLInputFactory.newInstance();\n\t\tstaxFactory.setXMLResolver( xmlResourceResolver );\n\t\treturn staxFactory;\n\t}\n\n\tprotected StartElement seekRootElementStartEvent(XMLEventReader staxEventReader, Origin origin) {\n\t\tXMLEvent rootElementStartEvent;\n\t\ttry {\n\t\t\trootElementStartEvent = staxEventReader.peek();\n\t\t\twhile ( rootElementStartEvent != null && !rootElementStartEvent.isStartElement() ) {\n\t\t\t\tstaxEventReader.nextEvent();\n\t\t\t\trootElementStartEvent = staxEventReader.peek();\n\t\t\t}\n\t\t}\n\t\tcatch ( Exception e ) {\n\t\t\tthrow new MappingException( \"Error accessing StAX stream\", e, origin );\n\t\t}\n\n\t\tif ( rootElementStartEvent == null ) {\n\t\t\tthrow new MappingException( \"Could not locate root element\", origin );\n\t\t}\n\n\t\treturn rootElementStartEvent.asStartElement();\n\t}\n\n\tprotected abstract <X extends T> Binding<X> doBind(XMLEventReader staxEventReader, StartElement rootElementStartEvent, Origin origin);\n\n\t@SuppressWarnings(\"unused\")\n\tprotected static boolean hasNamespace(StartElement startElement) {\n\t\treturn StringHelper.isNotEmpty( startElement.getName().getNamespaceURI() );\n\t}\n\n\tprotected <X extends T> X jaxb(XMLEventReader reader, Schema xsd, JAXBContext jaxbContext, Origin origin) {\n\t\tfinal ContextProvidingValidationEventHandler handler = new ContextProvidingValidationEventHandler();","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/AbstractBinder.java#L113-L149","documentation":"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.","triggerScenarios":"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.","commonSituations":"Partial uploads or interrupted writes producing truncated XML files; concurrent code closing shared streams; files consisting of a very long comment/doctype then EOF.","solutions":["Read the cause - it usually contains the underlying message ('Premature end of file', 'stream closed')","Open the file named by the Origin and check it is complete (compare size, re-save from source)","Ensure no other code closes or wraps the same stream during binding","Lint the file with any XML validator to confirm the prolog is intact"],"exampleFix":"<!-- before: truncated prolog -->\n<?xml version=\"1.0\"?>\n<!-- TODO finish this mapp\n\n<!-- after -->\n<?xml version=\"1.0\"?>\n<!-- attachment mappings -->\n<hibernate-mapping>...</hibernate-mapping>","handlingStrategy":"validation","validationCode":"// cheap sanity check: file exists, non-empty, and starts with '<' after BOM\nbyte[] head = Files.readAllBytes(path);\nString s = new String(head, java.nio.charset.StandardCharsets.UTF_8).trim();\nif (head.length == 0 || !s.startsWith(\"<\")) {\n    throw new IllegalStateException(path + \" does not look like readable XML\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    binder.bind(stream, origin);\n} catch (MappingException e) {\n    if (e.getMessage().contains(\"Error accessing StAX stream\")) {\n        // underlying stream broke mid-read: re-check file completeness, no concurrent closes\n    }\n    throw e;\n}","preventionTips":["Do not share or close streams from other threads during binding","Verify generated mapping files are fully written (atomic move/write-temp-then-rename)","Check for truncated files after interrupted builds"],"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"}