flowable/flowable-engine · error · FlowableException

Error converting process reference expression

Error message

Error converting process reference expression

What it means

Thrown while converting a CMMN <processRefExpression> element when the StAX reader fails to read the element text (XMLStreamException). The converter sets the expression on a ProcessTask; a broken or unreadable XML element aborts conversion with this wrapped FlowableException.

Source

Thrown at modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/ProcessRefExpressionXmlConverter.java:46

    @Override
    public String getXMLElementName() {
        return CmmnXmlConstants.ELEMENT_PROCESS_REF_EXPRESSION;
    }
    
    @Override
    public boolean hasChildElements() {
        return false;
    }

    @Override
    protected CmmnElement convert(XMLStreamReader xtr, ConversionHelper conversionHelper) {
        try {
            String expression = xtr.getElementText();
            if (StringUtils.isNotEmpty(expression) && conversionHelper.getCurrentCmmnElement() instanceof ProcessTask processTask) {
                processTask.setProcessRefExpression(expression);
            }
        } catch (XMLStreamException e) {
            throw new FlowableException("Error converting process reference expression", e);
        }
        return null;
    }
    
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the CMMN XML file and repair the <processRefExpression> element.
2. Inspect e.getCause() for the exact XMLStreamException location.
3. Ensure the expression element is well-formed, e.g. <processRefExpression>${someExpression}</processRefExpression>.
4. Re-export the diagram from the modeler.

Example fix

// before
<processRefExpression>${proc
// after
<processRefExpression>${processVariable}</processRefExpression>

// Validate XML well-formedness before conversion
javax.xml.validation.Validator v = schema.newValidator();
v.validate(new StreamSource(new File(cmmnPath)));

try {
    CmmnModel model = converter.convertToCmmnModel(in);
} catch (FlowableException e) {
    throw new IllegalStateException("CMMN XML invalid at processRefExpression: " + e.getCause(), e);
}

When it happens

Trigger: Parsing a CMMN model containing a <processRefExpression> child of a process task where the element text cannot be read due to malformed XML (unclosed tags, invalid characters, encoding issues).

Common situations: Hand-edited CMMN XML; XML generated with invalid characters; file encoding mismatch (e.g. UTF-16 file read as UTF-8).

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

• Error while reading {ATTRIBUTE_ELEMENT_NAME} extension eleme
• Error converting standard event
• Error converting text annotation
• Error converting timer expression
• Could not resolve key from expression: {eventType}

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