flowable/flowable-engine · error · XMLException

Error processing BPMN document

Error message

Error processing BPMN document

What it means

Top-level catch in convertToBpmnModel(XMLStreamReader): any Exception that is not already an XMLException (parse errors are rethrown unchanged) is logged with 'Error processing BPMN document' and wrapped in XMLException with this message. It signals an unexpected failure during model building — usually a converter bug or a semantically invalid model rather than pure XML syntax.

Source

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

                    }
                }
            }

            for (Process process : model.getProcesses()) {
                for (Pool pool : model.getPools()) {
                    if (process.getId().equals(pool.getProcessRef())) {
                        pool.setExecutable(process.isExecutable());
                    }
                }
                processFlowElements(process.getFlowElements(), process);
            }

        } catch (XMLException e) {
            throw e;

        } catch (Exception e) {
            LOGGER.error("Error processing BPMN document", e);
            throw new XMLException("Error processing BPMN document", e);
        }
        return model;
    }

    protected void processFlowElements(Collection<FlowElement> flowElementList, BaseElement parentScope) {
        for (FlowElement flowElement : flowElementList) {

            if (flowElement instanceof SequenceFlow sequenceFlow) {
                FlowNode sourceNode = getFlowNodeFromScope(sequenceFlow.getSourceRef(), parentScope);
                if (sourceNode != null) {
                    sourceNode.getOutgoingFlows().add(sequenceFlow);
                    sequenceFlow.setSourceFlowElement(sourceNode);
                }

                FlowNode targetNode = getFlowNodeFromScope(sequenceFlow.getTargetRef(), parentScope);
                if (targetNode != null) {
                    targetNode.getIncomingFlows().add(sequenceFlow);
                    sequenceFlow.setTargetFlowElement(targetNode);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Read the logged stack trace (LOGGER.error output) — the cause identifies the exact element/converter that failed.
2. Open the BPMN file in the Flowable modeler and re-save to normalize nonstandard constructs.
3. Check Flowable version compatibility between the tool that generated the XML and the runtime converter; upgrade flowable-bpmn-converter if needed.
4. If a custom converter/extension is involved, fix its handling of the offending element.

Example fix

// before
catch (XMLException e) { throw e; } // other exceptions fall through to generic wrap
// after (caller side)
try {
    BpmnModel m = converter.convertToBpmnModel(xtr);
} catch (XMLException e) {
    logger.error("Processing failed at element", e.getCause()); // inspect real cause
    throw e;
}

try {
    return converter.convertToBpmnModel(xtr);
} catch (XMLException e) {
    if ("Error processing BPMN document".equals(e.getMessage())) {
        // non-XMLException failure during model building — cause has the real stack
        throw new DeploymentException("Unexpected converter failure: " + e.getCause(), e);
    }
    throw e; // pure XML parse problems propagate as-is
}

When it happens

Trigger: An unexpected RuntimeException/Exception thrown while converting elements to the BpmnModel (e.g. NPE in a converter for an unusual element, ArrayIndexOutOfBounds on malformed attributes, ClassCastException) during convertToBpmnModel(XMLStreamReader).

Common situations: BPMN files with elements the converter doesn't expect (rare vendor extensions, wrong attribute types), Flowable version incompatibilities where a newer modeler emits elements an older converter mishandles, or bugs in custom converters registered into the XML converter.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• No converter for ${flowElement.getClass()} found
• No converter for ${artifact.getClass()} found
• BPMN XSD could not be found
• The bpmn 2.0 xml is not properly encoded
• Error while reading the BPMN 2.0 XML

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