flowable/flowable-engine · error · ActivitiException

Error parsing XML

Error message

Error parsing XML

What it means

BpmnParse.execute() wraps the whole XML parsing in a try/catch. Any exception that is neither an ActivitiException nor an XMLException (e.g. a low-level SAX/ParserConfigurationException/IOException) is wrapped in this generic 'Error parsing XML' ActivitiException with the original as cause.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/parser/BpmnParse.java:216

                        }

                    }
                }
            }

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

            // Validation successful (or no validation)
            transformProcessDefinitions();

        } catch (Exception e) {
            if (e instanceof ActivitiException) {
                throw (ActivitiException) e;
            } else if (e instanceof XMLException) {
                throw (XMLException) e;
            } else {
                throw new ActivitiException("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

1. Inspect the cause chain (e.getCause()) of the thrown ActivitiException to find the underlying parser error
2. Validate the XML is well-formed with an XML tool (xmllint / IDE validator) before deploying
3. Check file encoding and completeness; re-export or re-save the file as UTF-8
4. Compare JDK versions if the same file parses in one environment but not another

Example fix

// before: deploying a truncated file caught only at runtime
repositoryService.createDeployment().addClasspathResource("broken.bpmn20.xml").deploy();
// after: validate well-formedness first
DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.newDocumentBuilder().parse(new File("src/main/resources/broken.bpmn20.xml")); // throws early with precise message

// cheap well-formedness check before deploy
try {
  DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new InputSource(new StringReader(bpmnXml)));
} catch (SAXException | IOException e) {
  throw new IllegalStateException("BPMN XML not well-formed: " + e.getMessage());
}

try {
  repositoryService.createDeployment().addInputStream(name, xml).deploy();
} catch (ActivitiException e) {
  if ("Error parsing XML".equals(e.getMessage())) {
    Throwable cause = e.getCause(); // inspect SAX/IO/parser-config root cause
  }
}

When it happens

Trigger: Malformed XML that crashes the underlying parser (unbalanced tags, encoding errors, invalid characters); parser factory misconfiguration (e.g. invalid SAXParserFactory); I/O errors while reading the stream source.

Common situations: Deploying truncated or corrupted .bpmn/.bpmn20.xml files; files with wrong encoding (e.g. UTF-16 declared/undeclared); XML features like DTDs or entities triggering parser failures; JDK XML parser differences across environments.

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

• Error parsing XML
• Error while parsing BPMN model.
• Error parsing XML
• Error while parsing BPMN model.
• Errors while parsing: ${errorBuilder}

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