flowable/flowable-engine · error · CmmnXMLException

Error processing CMMN XML document

Error message

Error processing CMMN XML document

What it means

Any unexpected exception during CMMN XML model conversion (other than CmmnXMLException, which is rethrown unchanged) is caught, logged at error level, and rethrown as CmmnXMLException("Error processing CMMN XML document"). It is a catch-all indicating an internal failure while building the CmmnModel from the parsed XML.

Source

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

                    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) {
            throw e;

        } catch (Exception e) {
            LOGGER.error("Error processing CMMN XML document", e);
            throw new CmmnXMLException("Error processing CMMN XML document", e);
        }

        // Post process all elements: add instances where a reference is used
        processCmmnElements(conversionHelper);
        return conversionHelper.getCmmnModel();
    }

    public void validateModel(InputStreamProvider inputStreamProvider) throws Exception {
        Schema schema = createSchema();

        Validator validator = schema.newValidator();
        validator.validate(new StreamSource(inputStreamProvider.getInputStream()));
    }

    public void validateModel(XMLStreamReader xmlStreamReader) throws Exception {
        Schema schema = createSchema();

        Validator validator = schema.newValidator();

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Read the chained cause and the LOGGER.error stack trace to identify which element/attribute failed
  2. Fix the offending attribute/element in the CMMN XML (check numeric/date-typed values)
  3. Validate the document against the CMMN 1.1 XSD before deploying
  4. Upgrade/downgrade Flowable to match the tool that generated the CMMN file
Defensive patterns

Strategy: try-catch

Validate before calling

SchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Schema xsd = sf.newSchema(getClass().getResource("/org/flowable/cmmn/schema/CMMN11.xsd"));
xsd.newValidator().validate(new StreamSource(cmmnInputStream)); // throws if invalid

Try / catch

try {
    cmmnModel = converter.convertToCmmnModel(provider);
} catch (CmmnXMLException e) {
    log.error("CMMN conversion failed: " + e.getCause(), e.getCause());
    throw new DeploymentException("Case definition could not be processed", e);
}

Prevention

When it happens

Trigger: An element converter (elementConverters.get(...).convertToCmmnModel) throwing a RuntimeException, e.g. ClassCastException from an unexpected element value, NumberFormatException from a malformed attribute, or NPE in a converter due to a missing parent element.

Common situations: Hand-edited CMMN XML with attribute values of unexpected type/format (e.g. non-numeric attributes parsed as numbers), CMMN produced by other tools using extensions Flowable's converters do not expect, or Flowable version mismatches where converters changed.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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