{"record":{"id":"ea05d7f3e6b8c303","repo":"flowable/flowable-engine","slug":"could-not-start-case-instance-no-case-reference-d","errorCode":null,"errorMessage":"Could not start case instance: no case reference defined in ${planItemInstanceEntity}","messagePattern":"Could not start case instance: no case reference defined in (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/behavior/impl/CaseTaskActivityBehavior.java","lineNumber":82,"sourceCode":"        this.sameDeployment = caseTask.isSameDeployment();\n        this.caseTask = caseTask;\n    }\n\n    @Override\n    public void execute(CommandContext commandContext, PlanItemInstanceEntity planItemInstanceEntity, ChildTaskActivityBehavior.VariableInfo variableInfo) {\n        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);\n        CaseInstanceHelper caseInstanceHelper = CommandContextUtil.getCaseInstanceHelper(commandContext);\n\n        String caseDefinitionKey = null;\n        if (caseRefExpression != null) {\n            caseDefinitionKey = caseRefExpression.getValue(planItemInstanceEntity).toString();\n\n        } else if (StringUtils.isNotEmpty(caseRef)) {\n            caseDefinitionKey = caseRef;\n\n        }\n        if (StringUtils.isEmpty(caseDefinitionKey)) {\n            throw new FlowableException(\"Could not start case instance: no case reference defined in \" + planItemInstanceEntity);\n        }\n\n        CaseInstanceBuilder caseInstanceBuilder = new CaseInstanceBuilderImpl().caseDefinitionKey(caseDefinitionKey);\n        if (StringUtils.isNotEmpty(planItemInstanceEntity.getTenantId())) {\n            caseInstanceBuilder.tenantId(planItemInstanceEntity.getTenantId());\n            caseInstanceBuilder.overrideCaseDefinitionTenantId(planItemInstanceEntity.getTenantId());\n        }\n\n        caseInstanceBuilder.parentId(planItemInstanceEntity.getCaseInstanceId());\n\n        if (fallbackToDefaultTenant != null && fallbackToDefaultTenant) {\n            caseInstanceBuilder.fallbackToDefaultTenant();\n        }\n\n        Map<String, Object> finalVariableMap = new HashMap<>();\n        handleInParameters(planItemInstanceEntity, cmmnEngineConfiguration, finalVariableMap, cmmnEngineConfiguration.getExpressionManager());\n\n        // Needed for the form field handler later","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/behavior/impl/CaseTaskActivityBehavior.java#L64-L100","documentation":"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.","triggerScenarios":"Executing a case task plan item where neither 'caseDefinitionKey'/'caseDefinitionExpression' nor 'caseRef' ('caseReferenceExpression') yields a non-empty value in the CMMN case model.","commonSituations":"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.","solutions":["Add a caseDefinitionKey (or caseDefinitionExpression) attribute to the caseTask element in the CMMN XML.","Alternatively set caseRef/caseReferenceExpression if you intend to reference the case by reference name.","If using expressions, make sure the variables they reference are set before the case task activates.","Redeploy the case definition and restart the case instance."],"exampleFix":"// before\n<caseTask id=\"childCaseTask\" flowable:caseRef=\"\"/>\n// after\n<caseTask id=\"childCaseTask\" flowable:caseDefinitionKey=\"childCase\"/>","handlingStrategy":"validation","validationCode":"// Parse/inspect the deployed case model: every <caseTask> must have caseDefinitionKey or caseRef\nboolean ok = caseTaskElement.attributeValue(\"caseDefinitionKey\") != null\n    || caseTaskElement.attributeValue(\"caseRef\") != null;","typeGuard":null,"tryCatchPattern":"try {\n    cmmnRuntimeService.startCaseInstance(builder);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"no case reference defined\")) {\n        // fix the CMMN XML and redeploy\n    }\n}","preventionTips":["Model reviews: every caseTask needs caseDefinitionKey or caseRef","Validate case XML against schema before deployment","Ensure referenced case definitions are deployed","If using expressions, guard against null-resolving variables"],"tags":["cmmn","case-task","modeling","missing-attribute"],"backgroundTag":"empty-required-field","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}