flowable/flowable-engine · error · FlowableException

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

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.

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)

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 ${pla
• Could not resolve key from expression:
• Expression
• Error converting process reference expression
• Could not resolve key from expression: {eventType}

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