flowable/flowable-engine · error · CmmnXMLException

Error reading XML

Error message

Error reading XML

What it means

During the StAX event loop of convertToCmmnModel, if xtr.next() throws any exception the converter logs it at debug level and rethrows as CmmnXMLException("Error reading XML"). This is a low-level failure while pulling the next XML event from the document.

Source

Thrown at modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/CmmnXmlConverter.java:219

            throw new CmmnXMLException("Error while reading the CMMN 1.1 XML", e);
        } catch (IOException e) {
            throw new CmmnXMLException(e.getMessage(), e);
        }
    }

    public CmmnModel convertToCmmnModel(XMLStreamReader xtr) {

        ConversionHelper conversionHelper = new ConversionHelper();
        conversionHelper.setCmmnModel(new CmmnModel());

        try {
            String currentXmlElement = null;
            while (xtr.hasNext()) {
                try {
                    xtr.next();
                } catch (Exception e) {
                    LOGGER.debug("Error reading CMMN XML document", e);
                    throw new CmmnXMLException("Error reading XML", e);
                }

                if (xtr.isStartElement()) {
                    currentXmlElement = xtr.getLocalName();
                    if (elementConverters.containsKey(currentXmlElement)) {
                        elementConverters.get(currentXmlElement).convertToCmmnModel(xtr, conversionHelper);
                    }

                } else if (xtr.isEndElement()) {
                    currentXmlElement = null;
                    if (elementConverters.containsKey(xtr.getLocalName())) {
                        elementConverters.get(xtr.getLocalName()).elementEnd(xtr, conversionHelper);
                    }

                }
            }

        } catch (CmmnXMLException e) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Open the CMMN file in an XML editor/validator and fix the syntax at the reported location
2. Remove illegal control characters or invalid entity references from the XML
3. Re-generate the file from a modeling tool rather than hand-editing
4. Enable the converter's LOGGER debug output to see the original parser exception

Example fix

// before
<case ... description="line1&#x0; line2"> // illegal control char
// after
<case ... description="line1 line2">

try (Reader r = new InputStreamReader(in, StandardCharsets.UTF_8)) {
    char[] buf = new char[64]; int n = r.read(buf);
    if (n <= 0 || new String(buf, 0, n).trim().charAt(0) != '<') throw new IllegalStateException("Not XML content");
}

boolean looksLikeXml(InputStream in) {
    try { in.mark(16); byte[] b = new byte[16]; int n = in.read(b); in.reset();
        return n > 0 && new String(b, 0, n).trim().startsWith("<"); }
    catch (IOException e) { return false; }
}

try {
    cmmnModel = converter.convertToCmmnModel(xtr);
} catch (CmmnXMLException e) {
    log.debug("StAX parse failure", e.getCause()); // original parser exception was logged at debug
    throw new DeploymentException("CMMN XML unreadable at event level", e);
}

When it happens

Trigger: Calling convertToCmmnModel(XMLStreamReader) with a reader over a malformed or corrupted XML stream where the parser fails mid-document (invalid entities, illegal characters, unexpected EOF inside a tag).

Common situations: Same as generic malformed XML: truncated deployments, character encoding drift mid-file, invalid control characters pasted into the CMMN model, or XML containing illegal entity references.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Error reading XML
• Error processing CMMN XML document
• Error writing CMMN XML
• 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/cea8a469e4849a80. Report an issue: GitHub.