flowable/flowable-engine · error · ActivitiException

Error while parsing BPMN model.

Error message

Error while parsing BPMN model.

What it means

ProcessDiagramLayoutFactory.parseXml parses BPMN XML into a DOM Document using DocumentBuilder.parse to extract layout/diagram information. Any SAX/IO/parser failure is rethrown as ActivitiException('Error while parsing BPMN model.').

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/diagram/ProcessDiagramLayoutFactory.java:110

        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 ActivitiException("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 (e.g. with xmllint) before calling the API
  2. Ensure the InputStream is opened, readable, and positioned at the start
  3. Check the XML declaration encoding matches the actual byte encoding
Defensive patterns

Strategy: validation

Validate before calling

DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.setNamespaceAware(true);
try { f.newDocumentBuilder().parse(new File(bpmnPath)); } catch (Exception e) { throw new IllegalStateException("BPMN XML invalid", e); }

Try / catch

try {
    diagramLayout = factory.getProcessDiagramLayout(bpmnStream, imageStream);
} catch (org.activiti.engine.ActivitiException e) {
    if (e.getMessage().contains("Error while parsing BPMN model")) {
        // log e.getCause() and fall back to default layout
    }
}

Prevention

When it happens

Trigger: Calling the diagram-layout generation APIs (e.g. getProcessDiagramLayout) with a stream that is not well-formed XML, unreadable, or closed.

Common situations: Passing a non-XML stream (e.g. PNG image) as the BPMN XML input; encoding mismatches; truncated file downloads; XML with undeclared entities.

Related errors

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