What causes "Error reading documentation element" in flowable/flowable-engine?

Inspect and repair the element markup in the CMMN file.

flowable/flowable-engine · error · CmmnXMLException

Error reading documentation element

Error message

Error reading documentation element

What it means

Thrown by DocumentationXmlConverter.convert as a CmmnXMLException when any exception occurs while reading a CMMN <documentation> element (e.g. extracting its text or the documentationTextFormat attribute). It wraps parsing failures of the documentation section into a dedicated converter error.

Solutions

Inspect and repair the <documentation> element markup in the CMMN file.
Simplify documentation content to plain text, removing nested tags or invalid entities.
Run the file through an XML validator to find the exact syntax fault.

Example fix

<!-- before -->
<documentation textFormat="text/html"><b>Notes</b> & tips</documentation>
<!-- after -->
<documentation textFormat="text/plain">Notes &amp; tips</documentation>

Defensive patterns

Strategy: validation

Validate before calling

Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(cmmnFile); // fails fast on malformed <documentation> blocks

Try / catch

try {
    cmmnModel = converter.convertToCmmnModel(stream, encoding);
} catch (CmmnXMLException e) {
    if ("Error reading documentation element".equals(e.getMessage())) {
        // repair the documentation element
    }
    throw e;
}

Prevention

Keep documentation content as plain text or properly escaped HTML entities.
Run XSD validation as a pre-conversion step.
Use XML-aware editors rather than plain-text tools for CMMN files.

When it happens

Trigger: Reading the <documentation> element raises an exception: malformed XML, unexpected stream state, missing/invalid textFormat attribute handling, or I/O-level XML stream errors.

Common situations: Hand-edited documentation blocks with invalid markup; tool-generated CMMN with nested unsupported content inside documentation; encoding issues.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/DocumentationXmlConverter.java:52

    @Override
    protected CmmnElement convert(XMLStreamReader xtr, ConversionHelper conversionHelper) {
        try {
            String textFormat = xtr.getAttributeValue(null, CmmnXmlConstants.ATTRIBUTE_TEXT_FORMAT);
            if (StringUtils.isEmpty(textFormat)) {
                textFormat = "text/plain";
            }
            
            String documentation = xtr.getElementText();
            if (StringUtils.isNotEmpty(documentation)) {
                conversionHelper.getCurrentCmmnElement().setDocumentation(documentation);
                conversionHelper.getCurrentCmmnElement().setDocumentationTextFormat(textFormat);
            }
            
            return null;
            
        } catch (Exception e) {
            throw new CmmnXMLException("Error reading documentation element", e);
        }
    }
    
}

View on GitHub (pinned to d6d39ce1c6)