flowable/flowable-engine · error · XMLException

Error while reading the BPMN 2.0 XML

Error message

Error while reading the BPMN 2.0 XML

What it means

BpmnXMLConverter.convertToBpmnModel(InputStreamProvider, String) wraps any XMLStreamException raised while the StAX reader parses the first pass of the BPMN document (schema validation / initial convert) into XMLException with this fixed message. It signals the XML itself could not be read by the underlying parser, not that it failed validation rules.

Source

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

        if (xif.isPropertySupported(XMLConstants.ACCESS_EXTERNAL_DTD)) {
            xif.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, "");
        }
        
        if (xif.isPropertySupported(XMLConstants.ACCESS_EXTERNAL_SCHEMA)) {
            xif.setProperty(XMLConstants.ACCESS_EXTERNAL_SCHEMA, "");
        }

        if (validateSchema) {
            try (InputStreamReader in = new InputStreamReader(inputStreamProvider.getInputStream(), encoding)) {
                if (!enableSafeBpmnXml) {
                    validateModel(inputStreamProvider);
                } else {
                    validateModel(new FlowableXMLStreamReader(xif.createXMLStreamReader(in)));
                }
            } catch (UnsupportedEncodingException e) {
                throw new XMLException("The bpmn 2.0 xml is not properly encoded", e);
            } catch(XMLStreamException e){
                throw new XMLException("Error while reading the BPMN 2.0 XML", e);
            } catch(Exception e){
                throw new XMLException(e.getMessage(), e);
            }
        }
        // The input stream is closed after schema validation
        try (InputStreamReader in = new InputStreamReader(inputStreamProvider.getInputStream(), encoding)) {
            // XML conversion
            return convertToBpmnModel(xif.createXMLStreamReader(in));
        } catch (UnsupportedEncodingException e) {
            throw new XMLException("The bpmn 2.0 xml is not properly encoded", e);
        } catch (XMLStreamException e) {
            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) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the BPMN XML with an XML parser (xmllint or IDE) to find the malformation and fix the document.
2. Check the getCause() XMLStreamException location (line/column) in logs to pinpoint the broken spot.
3. Ensure the InputStream is fresh and not already consumed; re-open the resource before converting.
4. Verify the declared encoding matches the actual bytes of the file.

Example fix

// before
InputStream is = new FileInputStream(f);
bpmnXmlConverter.convertToBpmnModel(new DefaultInputStreamProvider(is), "UTF-8"); // stream reused earlier
// after
try (InputStream is = new FileInputStream(f)) {
    BpmnModel model = bpmnXmlConverter.convertToBpmnModel(new DefaultInputStreamProvider(is), "UTF-8");
} catch (XMLException e) {
    logger.error("Invalid BPMN XML at {}", e.getCause());
}

// Pre-validate the BPMN source is well-formed XML before converting
byte[] bytes = readAll(provider);
DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.setNamespaceAware(true);
f.newDocumentBuilder().parse(new ByteArrayInputStream(bytes)); // throws SAXParseException with line/col if malformed

try {
    BpmnModel m = converter.convertToBpmnModel(provider, "UTF-8");
} catch (XMLException e) {
    Throwable c = e.getCause();
    if (c instanceof XMLStreamException xse) {
        throw new DeploymentException("Invalid BPMN XML at line " + xse.getLocation().getLineNumber(), e);
    }
    throw e;
}

When it happens

Trigger: Calling convertToBpmnModel(inputStreamProvider, encoding) where the input stream yields malformed XML (unclosed tags, invalid characters, truncated document) causing the underlying XMLStreamReader to throw XMLStreamException during validateModel or the initial read.

Common situations: Deploying a .bpmn/.bpmn20.xml file that was truncated on upload, hand-edited with a typo, saved with an encoding mismatch, or produced by a tool emitting invalid XML; also reading a stream already consumed by a previous parse attempt.

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

• The bpmn 2.0 xml is not properly encoded
• e.getMessage()
• Error reading XML
• Error writing BPMN XML
• BPMN XSD could not be found

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