flowable/flowable-engine · error · FlowableException

Include in stage overview expression does not resolve to a…

Error message

Include in stage overview expression does not resolve to a boolean value <includeInStageOverviewValue>: <stageValueObject> for <planItemInstanceEntity>

What it means

When recording history for a plan item in a stage, the cmmn:includeInStageOverview attribute may be an expression. DefaultCmmnHistoryManager evaluates it and requires a Boolean result; anything else (String, Integer, null object) makes overview inclusion undecidable, so it throws FlowableException naming the expression text, the evaluated value and the plan item instance.

Solutions

1. Change the expression/variable so it evaluates to a real Boolean (true/false), e.g. ${isValid} where isValid is a java.lang.Boolean
2. Quote-check: literal 'true'/'false' strings in the attribute are handled without evaluation; only expressions must return Boolean
3. Initialize or rename the case variable referenced by the expression so it is non-null and boolean-typed

Example fix

// before (CMMN XML / variable)
<planItem ... cmmn:includeInStageOverview="${showInOverview}"> // showInOverview = "yes" (String)
// after
caseVariables.put("showInOverview", Boolean.TRUE);
<planItem ... cmmn:includeInStageOverview="${showInOverview}">

Object v = caseVariables.get("showInOverview"); if (!(v instanceof Boolean)) throw new IllegalStateException("showInOverview must be Boolean");

try { startCase(); } catch (FlowableException e) { if (e.getMessage().contains("Include in stage overview")) { fixExpressionOrVariable(); } }

When it happens

Trigger: A CMMN model where includeInStageOverview is set to an expression like ${someVar} that evaluates to a non-boolean (e.g. a string 'yes', a number, or null because the variable is unset) when the plan item instance reaches history recording.

Common situations: Expression returning 'true' as a String instead of boolean true; referenced case variable not initialized; copying an attribute value like "1"/"yes" expecting implicit conversion; spelling mistake in the variable name yielding null.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Category expression does not resolve to a string:
• documentation expression does not resolve to a string:
• Due date expression does not resolve to a Date, Instant…
• FormKey expression does not resolve to a string:
• Include in stage overview expression does not resolve to a…

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/DefaultCmmnHistoryManager.java:606

            String includeInStageOverviewValue = null;
            if (planItemInstanceEntity.isStage()) {
                if (planItemDefinition instanceof Stage stage) {
                    includeInStageOverviewValue = stage.getIncludeInStageOverview();
                }
                
            } else if (planItemDefinition instanceof Milestone milestone) {
                includeInStageOverviewValue = milestone.getIncludeInStageOverview();
            }
            
            if (StringUtils.isNotEmpty(includeInStageOverviewValue)) {
                if ("true".equalsIgnoreCase(includeInStageOverviewValue)) {
                    showInOverview = true;
                
                } else if (!"false".equalsIgnoreCase(includeInStageOverviewValue)) {
                    Expression stageExpression = cmmnEngineConfiguration.getExpressionManager().createExpression(includeInStageOverviewValue);
                    Object stageValueObject = stageExpression.getValue(planItemInstanceEntity);
                    if (!(stageValueObject instanceof Boolean)) {
                        throw new FlowableException("Include in stage overview expression does not resolve to a boolean value " + 
                                        includeInStageOverviewValue + ": " + stageValueObject + " for " + planItemInstanceEntity);
                    }
                    
                    showInOverview = (Boolean) stageValueObject;
                }
            }
        }
        
        return showInOverview;
    }
}

View on GitHub (pinned to d6d39ce1c6)