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

Inspect the wrapped cause (getCause()) — the real failure is there, not the message

flowable/flowable-engine · error · FlowableException

Error parsing XML

Error message

Error parsing XML

What it means

BpmnParse.execute() wraps the whole parse in a try/catch: unexpected exceptions that are neither FlowableException nor XMLException are rethrown as FlowableException("Error parsing XML", e) preserving the cause. It signals a generic, non-classified failure while parsing the BPMN model.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/parser/BpmnParse.java:206

            bpmnModel.setSourceSystemId(sourceSystemId);
            bpmnModel.setEventSupport(new FlowableEventSupport());

            // Validation successful (or no validation)

            // Attach logic to the processes (eg. map ActivityBehaviors to bpmn model elements)
            applyParseHandlers();

            // Finally, process the diagram interchange info
            processDI();

        } catch (Exception e) {
            if (e instanceof FlowableException) {
                throw (FlowableException) e;
            } else if (e instanceof XMLException) {
                throw (XMLException) e;
            } else {
                throw new FlowableException("Error parsing XML", e);
            }
        }

        return this;
    }

    public BpmnParse name(String name) {
        this.name = name;
        return this;
    }

    public BpmnParse sourceInputStream(InputStream inputStream) {
        if (name == null) {
            name("inputStream");
        }
        setStreamSource(new InputStreamSource(inputStream));
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the wrapped cause (getCause()) — the real failure is there, not the message
Verify the deployed resource is well-formed XML with correct encoding
Try parsing the file with a plain XML parser to isolate malformed content
Check JVM XML parser configuration (secure processing / feature flags) if the cause is a SAXException

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure well-formed XML before deploying
javax.xml.parsers.DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new File("process.bpmn20.xml"));

Try / catch

try {
    deploymentBuilder.deploy();
} catch (FlowableException e) {
    if ("Error parsing XML".equals(e.getMessage())) {
        Throwable cause = e.getCause();
        log.error("XML parse failed: {}", cause, cause);
    }
}

Prevention

Inspect getCause() — the real error is always wrapped
Ensure resources are UTF-8/valid XML before deployment
Check JVM SAX parser security features when causes are SAXException

When it happens

Trigger: Any unexpected exception during parsing — e.g. SAX/parser factory configuration errors, IOException reading the stream source, NPEs in custom parse handlers, or a missing/unsupported XML feature in the JDK's XML parser.

Common situations: Corrupt or non-XML file deployed as BPMN resource; incompatible parser features (XXE protection settings); custom parser hooks throwing runtime exceptions; encoding issues in the XML stream.

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/57d574dcc5c98ada. Report an issue: GitHub.