flowable/flowable-engine · error · FlowableException

Error while parsing BPMN model.

Error message

Error while parsing BPMN model.

What it means

ProcessDiagramLayoutFactory.parseXml parses the BPMN XML stream into a DOM Document using javax.xml.parsers.DocumentBuilder to extract diagram layout info. Any parse failure (malformed XML, IO error on the stream) is wrapped in this FlowableException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/diagram/ProcessDiagramLayoutFactory.java:114

        Map<String, DiagramElement> listOfBoundsForImage = transformBoundsForImage(diagramBoundsImage, diagramBoundsXml, listOfBounds);
        return new DiagramLayout(listOfBoundsForImage);
    }

    protected Document parseXml(InputStream bpmnXmlStream) {
        // Initiate DocumentBuilderFactory
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
        // Get one that understands namespaces
        factory.setNamespaceAware(true);

        DocumentBuilder builder;
        Document bpmnModel;
        try {
            // Get DocumentBuilder
            builder = factory.newDocumentBuilder();
            // Parse and load the Document into memory
            bpmnModel = builder.parse(bpmnXmlStream);
        } catch (Exception e) {
            throw new FlowableException("Error while parsing BPMN model.", e);
        }
        return bpmnModel;
    }

    protected DiagramNode getDiagramBoundsFromBpmnDi(Document bpmnModel) {
        Double minX = null;
        Double minY = null;
        Double maxX = null;
        Double maxY = null;

        // Node positions and dimensions
        NodeList setOfBounds = bpmnModel.getElementsByTagNameNS(BpmnParser.BPMN_DC_NS, "Bounds");
        for (int i = 0; i < setOfBounds.getLength(); i++) {
            Element element = (Element) setOfBounds.item(i);
            Double x = Double.valueOf(element.getAttribute("x"));
            Double y = Double.valueOf(element.getAttribute("y"));
            Double width = Double.valueOf(element.getAttribute("width"));
            Double height = Double.valueOf(element.getAttribute("height"));

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the BPMN XML is well-formed (xmllint or an XML editor) before using diagram layout generation
2. Ensure the InputStream is open, positioned at start, and contains the BPMN XML bytes
3. Check the XML declaration/encoding matches the actual byte encoding of the stream
4. Inspect the wrapped cause exception for the exact SAX parser error and line number

Example fix

// before
factory.getProcessDiagramLayout(bpmnXmlStream, imageStream);

// after: validate XML first
try (InputStream in = new ByteArrayInputStream(bpmnXml.getBytes(StandardCharsets.UTF_8))) {
    Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(in); // fails fast with a clear error
} catch (Exception e) {
    throw new IllegalArgumentException("Invalid BPMN XML: " + e.getMessage(), e);
}

DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.newDocumentBuilder().parse(new ByteArrayInputStream(bpmnXml.getBytes(StandardCharsets.UTF_8))); // throws early if malformed

try {
    layout = factory.getProcessDiagramLayout(xmlStream, imageStream);
} catch (FlowableException e) {
    if (e.getMessage().equals("Error while parsing BPMN model.")) {
        logger.error("BPMN XML malformed: {}", e.getCause().getMessage());
    }
}

When it happens

Trigger: getBpmnProcessDiagramLayout is given BPMN XML that DocumentBuilder.parse cannot handle: not well-formed XML, wrong encoding, empty/closed stream. Reached via bpmnModel().

Common situations: Hand-edited BPMN files with syntax errors; XML with undeclared entities/encoding issues; passing an already-consumed or null InputStream; non-XML content accidentally passed as BPMN XML.

Related errors

• Error while evaluating the following XPath expression on a B
• Error parsing XML
• Error while parsing BPMN model.
• Error parsing XML
• The bpmn 2.0 xml is not properly encoded

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