{"record":{"id":"690263fae0bfc1b3","repo":"flowable/flowable-engine","slug":"error-reading-documentation-element","errorCode":null,"errorMessage":"Error reading documentation element","messagePattern":"Error reading documentation element","errorType":"exception","errorClass":"CmmnXMLException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/DocumentationXmlConverter.java","lineNumber":52,"sourceCode":"\n    @Override\n    protected CmmnElement convert(XMLStreamReader xtr, ConversionHelper conversionHelper) {\n        try {\n            String textFormat = xtr.getAttributeValue(null, CmmnXmlConstants.ATTRIBUTE_TEXT_FORMAT);\n            if (StringUtils.isEmpty(textFormat)) {\n                textFormat = \"text/plain\";\n            }\n            \n            String documentation = xtr.getElementText();\n            if (StringUtils.isNotEmpty(documentation)) {\n                conversionHelper.getCurrentCmmnElement().setDocumentation(documentation);\n                conversionHelper.getCurrentCmmnElement().setDocumentationTextFormat(textFormat);\n            }\n            \n            return null;\n            \n        } catch (Exception e) {\n            throw new CmmnXMLException(\"Error reading documentation element\", e);\n        }\n    }\n    \n}","sourceCodeStart":34,"sourceCodeEnd":56,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/DocumentationXmlConverter.java#L34-L56","documentation":"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.","triggerScenarios":"Reading the <documentation> element raises an exception: malformed XML, unexpected stream state, missing/invalid textFormat attribute handling, or I/O-level XML stream errors.","commonSituations":"Hand-edited documentation blocks with invalid markup; tool-generated CMMN with nested unsupported content inside documentation; encoding issues.","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."],"exampleFix":"<!-- before -->\n<documentation textFormat=\"text/html\"><b>Notes</b> & tips</documentation>\n<!-- after -->\n<documentation textFormat=\"text/plain\">Notes &amp; tips</documentation>","handlingStrategy":"validation","validationCode":"Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(cmmnFile); // fails fast on malformed <documentation> blocks","typeGuard":null,"tryCatchPattern":"try {\n    cmmnModel = converter.convertToCmmnModel(stream, encoding);\n} catch (CmmnXMLException e) {\n    if (\"Error reading documentation element\".equals(e.getMessage())) {\n        // repair the documentation element\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["cmmn","xml","documentation"],"backgroundTag":"file-read-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}