flowable/flowable-engine · error · FlowableException

Unknown property used in expression:

Error message

Unknown property used in expression: 

What it means

JuelExpression.getValue wraps PropertyNotFoundException in FlowableException('Unknown property used in expression: <expr> with <variableContainer>'). The expression referenced a property/variable that the EL resolver could not resolve against the available variables, and Flowable converts it into an engine-level exception with the expression text attached.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/el/JuelExpression.java:54

    protected ExpressionManager expressionManager;

    public JuelExpression(ExpressionManager expressionManager, ValueExpression valueExpression, String expressionText) {
        this.valueExpression = valueExpression;
        this.expressionText = expressionText;
        this.expressionManager = expressionManager;
    }
    
    @Override
    public Object getValue(VariableContainer variableContainer) {
        ELContext elContext = expressionManager.getElContext(variableContainer);
        Object originalVariableContainer = elContext.getContext(VariableContainer.class);
        elContext.putContext(VariableContainer.class, variableContainer);
        Object originalValueContext = elContext.getContext(EvaluationState.class);
        elContext.putContext(EvaluationState.class, EvaluationState.READ);
        try {
            return resolveGetValueExpression(elContext);
        } catch (PropertyNotFoundException pnfe) {
            throw new FlowableException("Unknown property used in expression: " + expressionText + " with " + variableContainer, pnfe);
        } catch (MethodNotFoundException mnfe) {
            throw new FlowableException("Unknown method used in expression: " + expressionText + " with " + variableContainer, mnfe);
        } catch (FlowableException ex) {
            throw ex;
        } catch (Exception e) {
            throw new FlowableException("Error while evaluating expression: " + expressionText + " with " + variableContainer, e);
        } finally {
            elContext.putContext(EvaluationState.class, originalValueContext);
            elContext.putContext(VariableContainer.class, originalVariableContainer);
        }
    }

    protected Object resolveGetValueExpression(ELContext elContext) {
        return valueExpression.getValue(elContext);
    }

    @Override
    public void setValue(Object value, VariableContainer variableContainer) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check the expression text in the error and confirm the variable name matches what was actually set via execution.setVariable / taskService.setVariable
2. Set the variable before the expression is evaluated, or give it a default (e.g. ${myVar != null ? myVar : 'default'})
3. If resolving a bean property, verify the bean exists and the getter name/property spelling is correct

Example fix

// before
${order.totl}  // property typo
// after
${order.total}

boolean resolvable = variableContainer.getVariable(name) != null; // check before evaluating ${name.field}

boolean hasVariable(VariableContainer c, String n) { return c.getVariable(n) != null; }

try { value = expr.getValue(ctx); } catch (FlowableException e) { if (e.getCause() instanceof PropertyNotFoundException) { // handle missing variable: default or abort
    value = defaultValue; } else throw e; }

When it happens

Trigger: Evaluating ${someVar.field} where someVar is not present in the VariableContainer (execution, task, delegate) or a nested property does not exist on the resolved bean.

Common situations: Misspelled variable names in BPMN condition/assignment expressions; variable not yet set when the expression runs; renaming a Java bean property without updating process definitions; delegate beans not registered in the beans map.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Unknown method used in expression:
• Error while evaluating expression:
• Post upgrade expression can't be empty or null.
• text is null
• bytes array is null

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