What causes "Error while evaluating expression: ${expressionText}" in flowable/flowable-engine?

Inspect the cause chain of the ActivitiException — the root exception points at the real failure inside the expression evaluation.

flowable/flowable-engine · error · ActivitiException

Error while evaluating expression

Error message

Error while evaluating expression: ${expressionText}

What it means

JuelExpression.getValue catches ELException and any other Exception while evaluating the expression and wraps it into this ActivitiException carrying the expression text as cause. Unlike unknown property/method, this signals the expression resolved but evaluation itself failed (exception in invoked code, type conversion, resolver misconfiguration).

Solutions

Inspect the cause chain of the ActivitiException — the root exception points at the real failure inside the expression evaluation.
Fix the underlying bug in the method/bean invoked by the expression (null checks, argument types).
Add null guards in the expression itself: ${myVar != null ? myService.doIt(myVar) : ''}.
Verify the process engine configuration registers the correct resolvers (Spring/beans resolver) for the variables referenced.

Example fix

// before: NPE inside invoked bean
public BigDecimal total(Order o){ return o.getAmount(); }
// after
public BigDecimal total(Order o){ return o == null ? BigDecimal.ZERO : o.getAmount(); }

Defensive patterns

Strategy: try-catch

Validate before calling

// Guard inputs used inside expressions before evaluating:
Object o = container.getVariable("order");
if (o == null) throw new IllegalStateException("'order' variable required before expression evaluation");

Try / catch

try {
  Object v = juelExpression.getValue(container);
} catch (ActivitiException e) {
  Throwable root = e;
  while (root.getCause() != null) root = root.getCause();
  logger.error("Expression '{}' failed due to {}", e.getMessage(), root, e);
  throw e;
}

Prevention

Always log/inspect the cause chain — the root cause identifies the failing code inside the expression.
Add null checks at the start of bean methods called from expressions.
Avoid complex logic in EL; move it to JavaDelegate code that can be unit-tested.
Cover expression evaluation paths with integration tests using realistic variable values.

When it happens

Trigger: The expression ${...} resolved to a method/property whose invocation threw (NPE inside the delegate method, ClassCastException during EL coercion), or the EL context/resolver itself failed (e.g. missing ELResolver for the variable).

Common situations: NullPointerException inside a bean method called from an expression, type mismatch between process variable and expected parameter, custom ELResolver throwing, or evaluation during deserialization with missing context.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/el/JuelExpression.java:59

        this.valueExpression = valueExpression;
        this.expressionText = expressionText;
    }

    @Override
    public Object getValue(VariableContainer variableContainer) {
        ELContext elContext = Context.getProcessEngineConfiguration().getExpressionManager().getElContext((VariableScope) variableContainer);
        try {
            ExpressionGetInvocation invocation = new ExpressionGetInvocation(valueExpression, elContext);
            Context.getProcessEngineConfiguration()
                    .getDelegateInterceptor()
                    .handleInvocation(invocation);
            return invocation.getInvocationResult();
        } catch (PropertyNotFoundException pnfe) {
            throw new ActivitiException("Unknown property used in expression: " + expressionText, pnfe);
        } catch (MethodNotFoundException mnfe) {
            throw new ActivitiException("Unknown method used in expression: " + expressionText, mnfe);
        } catch (ELException ele) {
            throw new ActivitiException("Error while evaluating expression: " + expressionText, ele);
        } catch (Exception e) {
            throw new ActivitiException("Error while evaluating expression: " + expressionText, e);
        }
    }
    
    @Override
    public void setValue(Object value, VariableContainer variableContainer) {
        ELContext elContext = Context.getProcessEngineConfiguration().getExpressionManager().getElContext((VariableScope) variableContainer);
        try {
            ExpressionSetInvocation invocation = new ExpressionSetInvocation(valueExpression, elContext, value);
            Context.getProcessEngineConfiguration()
                    .getDelegateInterceptor()
                    .handleInvocation(invocation);
        } catch (Exception e) {
            throw new ActivitiException("Error while evaluating expression: " + expressionText, e);
        }
    }

View on GitHub (pinned to d6d39ce1c6)