flowable/flowable-engine · error · FlowableException

Could not start case instance: no case reference defined in

Error message

Could not start case instance: no case reference defined in ${planItemInstanceEntity}

What it means

CaseTaskActivityBehavior.execute determines the child case definition from the case definition key or case reference attribute of the case task. If both resolve to empty, it cannot start the child case instance and throws this error. The case task model must reference a case to start.

Source

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

        this.sameDeployment = caseTask.isSameDeployment();
        this.caseTask = caseTask;
    }

    @Override
    public void execute(CommandContext commandContext, PlanItemInstanceEntity planItemInstanceEntity, ChildTaskActivityBehavior.VariableInfo variableInfo) {
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        CaseInstanceHelper caseInstanceHelper = CommandContextUtil.getCaseInstanceHelper(commandContext);

        String caseDefinitionKey = null;
        if (caseRefExpression != null) {
            caseDefinitionKey = caseRefExpression.getValue(planItemInstanceEntity).toString();

        } else if (StringUtils.isNotEmpty(caseRef)) {
            caseDefinitionKey = caseRef;

        }
        if (StringUtils.isEmpty(caseDefinitionKey)) {
            throw new FlowableException("Could not start case instance: no case reference defined in " + planItemInstanceEntity);
        }

        CaseInstanceBuilder caseInstanceBuilder = new CaseInstanceBuilderImpl().caseDefinitionKey(caseDefinitionKey);
        if (StringUtils.isNotEmpty(planItemInstanceEntity.getTenantId())) {
            caseInstanceBuilder.tenantId(planItemInstanceEntity.getTenantId());
            caseInstanceBuilder.overrideCaseDefinitionTenantId(planItemInstanceEntity.getTenantId());
        }

        caseInstanceBuilder.parentId(planItemInstanceEntity.getCaseInstanceId());

        if (fallbackToDefaultTenant != null && fallbackToDefaultTenant) {
            caseInstanceBuilder.fallbackToDefaultTenant();
        }

        Map<String, Object> finalVariableMap = new HashMap<>();
        handleInParameters(planItemInstanceEntity, cmmnEngineConfiguration, finalVariableMap, cmmnEngineConfiguration.getExpressionManager());

        // Needed for the form field handler later

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add a caseDefinitionKey (or caseDefinitionExpression) attribute to the caseTask element in the CMMN XML.
2. Alternatively set caseRef/caseReferenceExpression if you intend to reference the case by reference name.
3. If using expressions, make sure the variables they reference are set before the case task activates.
4. Redeploy the case definition and restart the case instance.

Example fix

// before
<caseTask id="childCaseTask" flowable:caseRef=""/>
// after
<caseTask id="childCaseTask" flowable:caseDefinitionKey="childCase"/>

// Parse/inspect the deployed case model: every <caseTask> must have caseDefinitionKey or caseRef
boolean ok = caseTaskElement.attributeValue("caseDefinitionKey") != null
    || caseTaskElement.attributeValue("caseRef") != null;

try {
    cmmnRuntimeService.startCaseInstance(builder);
} catch (FlowableException e) {
    if (e.getMessage().contains("no case reference defined")) {
        // fix the CMMN XML and redeploy
    }
}

When it happens

Trigger: Executing a case task plan item where neither 'caseDefinitionKey'/'caseDefinitionExpression' nor 'caseRef' ('caseReferenceExpression') yields a non-empty value in the CMMN case model.

Common situations: Case task element in the XML missing both caseDefinitionKey and caseRef attributes; expression attributes resolving to null/empty because variables are unset; deployment of an incomplete case model.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Can only trigger a plan item that is in the ACTIVE state
• Cannot trigger case task plan item instance : no reference i
• Cannot trigger case task plan item instance : reference type
• Can only delete a child entity for a plan item with referenc
• Could not start process instance: no externalRef defined for

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