What causes "Error reading XML" in flowable/flowable-engine?

Enable debug logging for BpmnXMLConverter to see the logged 'Error reading XML document' stack trace with parser location.

flowable/flowable-engine · error · XMLException

Error reading XML

Error message

Error reading XML

What it means

Inside convertToBpmnModel(XMLStreamReader), each xtr.next() pull is wrapped: if advancing the StAX cursor throws, the converter logs at debug and throws XMLException("Error reading XML"). This means the XML token stream broke mid-iteration while walking the BPMN document.

Source

Thrown at modules/flowable-bpmn-converter/src/main/java/org/flowable/bpmn/converter/BpmnXMLConverter.java:331

            throw new XMLException("Error while reading the BPMN 2.0 XML", e);
        } catch (IOException e) {
            throw new XMLException(e.getMessage(), e);
        }
    }

    public BpmnModel convertToBpmnModel(XMLStreamReader xtr) {
        BpmnModel model = new BpmnModel();
        model.setStartEventFormTypes(startEventFormTypes);
        model.setUserTaskFormTypes(userTaskFormTypes);
        try {
            Process activeProcess = new Process();
            List<SubProcess> activeSubProcessList = new ArrayList<>();
            while (xtr.hasNext()) {
                try {
                    xtr.next();
                } catch (Exception e) {
                    LOGGER.debug("Error reading XML document", e);
                    throw new XMLException("Error reading XML", e);
                }

                if (xtr.isEndElement() && (ELEMENT_SUBPROCESS.equals(xtr.getLocalName()) ||
                        ELEMENT_TRANSACTION.equals(xtr.getLocalName()) ||
                        ELEMENT_ADHOC_SUBPROCESS.equals(xtr.getLocalName()))) {

                    activeSubProcessList.remove(activeSubProcessList.size() - 1);
                }

                if (!xtr.isStartElement()) {
                    continue;
                }

                if (ELEMENT_DEFINITIONS.equals(xtr.getLocalName())) {
                    definitionsParser.parse(xtr, model);

                } else if (ELEMENT_RESOURCE.equals(xtr.getLocalName())) {
                    resourceParser.parse(xtr, model);

View on GitHub (pinned to d6d39ce1c6)

Solutions

Enable debug logging for BpmnXMLConverter to see the logged 'Error reading XML document' stack trace with parser location.
Repair the malformed XML at the reported location.
Serve the converter from a complete, local (non-streaming) byte source so partial reads can't happen.
Re-export the BPMN file from its authoring tool.

Example fix

// before
XMLStreamReader xtr = factory.createXMLStreamReader(socket.getInputStream());
// after
byte[] full = readFully(socket.getInputStream()); // ensure complete document before parsing
XMLStreamReader xtr = factory.createXMLStreamReader(new ByteArrayInputStream(full));

Defensive patterns

Strategy: try-catch

Try / catch

try {
    BpmnModel model = converter.convertToBpmnModel(xtr);
} catch (XMLException e) {
    if ("Error reading XML".equals(e.getMessage())) {
        // token stream broke mid-iteration; full cause logged at debug by the converter
        log.debug("StAX cursor failed mid-document", e);
    }
    throw new DeploymentException("BPMN document unreadable", e);
}

Prevention

Enable DEBUG logging on BpmnXMLConverter to capture the underlying parser error location
Parse from a complete in-memory byte array, not a live network stream
Validate documents with a DOM/SAX pass before StAX conversion

When it happens

Trigger: convertToBpmnModel(XMLStreamReader) iterating xtr.hasNext()/next() when the underlying reader encounters malformed content, an unexpected end of document, or I/O failure from the source stream partway through parsing.

Common situations: Same mid-document corruption as other parse errors: truncated uploads, invalid characters after a valid prefix, or a reader built over a network stream that dropped mid-read.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/4e320c96eda814a9. Report an issue: GitHub.