flowable/flowable-engine · error · FlowableException

Unable to resolve expression value for

Error message

Unable to resolve expression value for ${value} in ${planItemInstanceEntity}

What it means

CasePageTaskActivityBehaviour.getExpressionValue evaluates a configured expression for the page task and requires a non-null result to return as a String. When the expression resolves to null (variable unset, property missing, expression typo), it throws this error. It enforces that required task attributes actually resolve at runtime.

Solutions

1. Ensure the referenced variable is set before the page task plan item becomes active (case variable, in-parameter mapping, or form data).
2. Check the expression text in the case model for typos or wrong property paths.
3. Provide a default in the expression, e.g. ${myVar != null ? myVar : 'default'} if the behavior accepts it.
4. Validate the start/incoming payload contains all required fields for the page task.

Example fix

// before
caseInstanceBuilder.variable("formKey", null); // page task ${formKey} resolves to null -> error
// after
caseInstanceBuilder.variable("formKey", "my-page-form");

Object v = caseInstance.getCaseVariables().get("formKey");
if (v == null) throw new IllegalArgumentException("formKey variable must be set before the page task activates");

try {
    cmmnRuntimeService.startCaseInstance(builder);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Unable to resolve expression value")) {
        // supply missing variable and retry
    }
}

When it happens

Trigger: Executing a CasePageTask plan item whose formKey/document/etc. attribute is an expression like ${myVar} and myVar is not set (no case variable, no task payload, or the variable is null).

Common situations: Variable name typo in the CMMN XML attribute; variable never initialized before the page task activates; expression evaluates against wrong scope; null form key supplied by caller or REST start.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Could not execute decision: no externalRef defined for
• Could not resolve key from expression:
• Expression
• Can only use a collection of String elements for…
• Category expression does not resolve to a string:

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/behavior/impl/CasePageTaskActivityBehaviour.java:125

    @Override
    public void onParentEnd(CommandContext commandContext, PlanItemInstanceEntity planItemInstanceEntity, String parentEndTransition, String exitEventType) {
        // a case page is working differently from default plan items as it gets completed, if its parent is completed and is terminated otherwise
        // delegate the completion on parent complete or an exit sentry having exit event type complete or force complete
        if (PlanItemTransition.COMPLETE.equals(parentEndTransition) || EXIT_EVENT_TYPE_COMPLETE.equals(exitEventType) || EXIT_EVENT_TYPE_FORCE_COMPLETE.equals(exitEventType)) {
            CommandContextUtil.getAgenda(commandContext).planCompletePlanItemInstanceOperation(planItemInstanceEntity);
        } else {
            CommandContextUtil.getAgenda(commandContext).planTerminatePlanItemInstanceOperation(planItemInstanceEntity, null, null);
        }
    }

    protected String getExpressionValue(String value, PlanItemInstanceEntity planItemInstanceEntity, ExpressionManager expressionManager) {
        Object expressionValue = expressionManager.createExpression(value).getValue(planItemInstanceEntity);
        if (expressionValue != null) {
            return expressionValue.toString();
        }
        
        throw new FlowableException("Unable to resolve expression value for " + value + " in " + planItemInstanceEntity);
    }
    
    protected Collection<String> getExpressionListValue(String value, PlanItemInstanceEntity planItemInstanceEntity, ExpressionManager expressionManager) {
        Object expressionValue = expressionManager.createExpression(value).getValue(planItemInstanceEntity);
        Collection<String> candidates = CandidateUtil.extractCandidates(expressionValue);
        return candidates;
    }
}

View on GitHub (pinned to d6d39ce1c6)