{"record":{"id":"2623c7cefd24470e","repo":"flowable/flowable-engine","slug":"casedefinitionkey-and-casedefinitionid-are-null","errorCode":null,"errorMessage":"caseDefinitionKey and caseDefinitionId are null","messagePattern":"caseDefinitionKey and caseDefinitionId are null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceHelperImpl.java","lineNumber":183,"sourceCode":"            CmmnDeploymentManager deploymentManager = cmmnEngineConfiguration.getDeploymentManager();\n            caseDefinition = deploymentManager.findDeployedCaseDefinitionById(caseDefinitionId);\n\n        } else if (caseInstanceBuilder.getCaseDefinitionKey() != null) {\n            String caseDefinitionKey = caseInstanceBuilder.getCaseDefinitionKey();\n            String tenantId = caseInstanceBuilder.getTenantId();\n            String parentDeploymentId = caseInstanceBuilder.getCaseDefinitionParentDeploymentId();\n\n            caseDefinition = resolveCaseDefinition(caseDefinitionKey, tenantId,\n                    caseInstanceBuilder.isFallbackToDefaultTenant() || cmmnEngineConfiguration.isFallbackToDefaultTenant(),\n                    parentDeploymentId);\n\n            if (caseDefinition != null && tenantId != null && !CmmnEngineConfiguration.NO_TENANT_ID.equals(tenantId)\n                    && !tenantId.equals(caseDefinition.getTenantId())) {\n                // Case definition comes from the fallback to the default tenant\n                caseInstanceBuilder.overrideCaseDefinitionTenantId(tenantId);\n            }\n        } else {\n            throw new FlowableIllegalArgumentException(\"caseDefinitionKey and caseDefinitionId are null\");\n        }\n        return caseDefinition;\n    }\n\n    protected CaseInstanceEntity startCaseInstance(CommandContext commandContext, CaseDefinition caseDefinition, CaseInstanceBuilder caseInstanceBuilder) {\n        CmmnModel cmmnModel = getCmmnModel(commandContext, caseDefinition);\n        Case caseModel = getCaseModel(caseDefinition, cmmnModel);\n        CaseInstanceEntity caseInstanceEntity = initializeCaseInstanceEntity(commandContext, caseDefinition, \n                cmmnModel, caseModel, caseInstanceBuilder);\n\n        if (!caseModel.isAsync()) {\n            // The InitPlanModelOperation will take care of initializing all the child plan items of that stage\n            CommandContextUtil.getAgenda(commandContext).planInitPlanModelOperation(caseInstanceEntity);\n\n            CaseInstanceLifeCycleListenerUtil.callLifecycleListeners(commandContext, caseInstanceEntity, \"\", CaseInstanceState.ACTIVE);\n\n            FlowableEventDispatcher eventDispatcher = cmmnEngineConfiguration.getEventDispatcher();\n            if (eventDispatcher != null && eventDispatcher.isEnabled()) {","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceHelperImpl.java#L165-L201","documentation":"CaseInstanceHelperImpl.getCaseDefinition resolves a CaseDefinition either by caseDefinitionId or by caseDefinitionKey (via the deployment cache/repository). If the CaseInstanceBuilder supplied neither identifier, the engine cannot locate which case definition to start and throws FlowableIllegalArgumentException. This is a fail-fast guard because starting a case without a definition reference is meaningless.","triggerScenarios":"Calling CmmnRuntimeService.startCaseInstance (or the async variant) with a CaseInstanceBuilder where both caseDefinitionId and caseDefinitionKey are null/never set.","commonSituations":"Building the start request dynamically from user input or a request payload where the definition reference key was omitted; copying builder code that set the id but was refactored; REST/API layer dropping the field when deserializing the start request.","solutions":["Set caseDefinitionKey (e.g. builder.caseDefinitionKey(\"myCase\")) before calling startCaseInstance.","Alternatively set the exact caseDefinitionId if you resolved the deployed definition already.","Validate the incoming request/dto for a non-null definition key or id before invoking the engine."],"exampleFix":"// before\ncmmnRuntimeService.createCaseInstanceBuilder().businessKey(\"BK-1\").start();\n// after\ncmmnRuntimeService.createCaseInstanceBuilder()\n    .caseDefinitionKey(\"loanApplicationCase\")\n    .businessKey(\"BK-1\")\n    .start();","handlingStrategy":"validation","validationCode":"if (caseDefinitionKey == null && caseDefinitionId == null) {\n    throw new IllegalArgumentException(\"Provide caseDefinitionKey or caseDefinitionId before starting a case instance\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.createCaseInstanceBuilder().caseDefinitionKey(key).start();\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"caseDefinitionKey and caseDefinitionId are null\")) {\n        // surface a 400 to the caller indicating the definition reference is required\n    }\n    throw e;\n}","preventionTips":["Always set at least caseDefinitionKey in every CaseInstanceBuilder usage.","Validate the start-request DTO at the controller/API layer before touching the engine.","Write a unit test asserting a start without a definition reference fails fast in your own layer."],"tags":["null-argument","cmmn","case-instance","illegal-argument"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}