What causes "Unknown property used in expression: ${expressionText}" in flowable/flowable-engine?

Verify the identifier inside ${...} matches an existing process variable or registered bean exactly (check spelling and case).

flowable/flowable-engine · error · ActivitiException

Unknown property used in expression

Error message

Unknown property used in expression: ${expressionText}

What it means

JuelExpression.getValue evaluates a JUEL expression against an EL context. When the underlying EL resolver throws PropertyNotFoundException — the referenced bean/property does not exist — the engine wraps it in an ActivitiException with the expression text. It means an identifier in a ${...} expression could not be resolved.

Solutions

Verify the identifier inside ${...} matches an existing process variable or registered bean exactly (check spelling and case).
If it is a Spring bean, confirm it is present in the application context and that the resolver is configured (processEngineConfiguration with Spring beans resolver).
Ensure the variable is set before the expression is evaluated (e.g. set it in an earlier service task or via execution.setVariable).
Use a null-safe construct like ${myVar != null ? myVar.x : 'default'} if the property may be absent.

Example fix

// before
String name = (String) execution.getVariable("usreName"); // typo → ${usreName.name} fails
// after
String name = (String) execution.getVariable("userName");

Defensive patterns

Strategy: validation

Validate before calling

// Validate that referenced variables/beans exist before the service task executes:
if (execution.getVariable("userName") == null) {
  throw new IllegalStateException("Process variable 'userName' must be set before expression evaluation");
}

Type guard

boolean resolvable(Object o) { return o != null; }

Try / catch

try {
  Object v = juelExpression.getValue(container);
} catch (ActivitiException e) {
  if (e.getCause() instanceof PropertyNotFoundException) {
    // fall back to default variable value
    v = defaultValue;
  } else { throw e; }
}

Prevention

Lint BPMN expressions against known process variables and bean names in CI.
Initialize required variables at process start or before the referencing task.
Use null-safe EL forms (${x != null ? x : default}) for optional values.
Keep bean names and property names consistent (case-sensitive).

When it happens

Trigger: Evaluating an expression like ${myBean.myProperty} during getValue (e.g. via setValues of a field injection) where myBean or myProperty is not registered (no Spring bean, missing process variable, wrong case).

Common situations: Typos in variable/bean names in BPMN expressions, referencing a Spring bean that isn't in the application context, missing process variable at that execution point, or case-sensitive property names.

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

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

Appendix: source

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

    protected String expressionText;
    protected ValueExpression valueExpression;

    public JuelExpression(ValueExpression valueExpression, String expressionText) {
        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) {

View on GitHub (pinned to d6d39ce1c6)