{"record":{"id":"4e57777e83f82bfe","repo":"flowable/flowable-engine","slug":"case-instance-id-is-required","errorCode":null,"errorMessage":"Case instance id is required","messagePattern":"Case instance id is required","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/ChangePlanItemStateCmd.java","lineNumber":48,"sourceCode":"    protected ChangePlanItemStateBuilderImpl changePlanItemStateBuilder;\n\n    public ChangePlanItemStateCmd(ChangePlanItemStateBuilderImpl changePlanItemStateBuilder, CmmnEngineConfiguration cmmnEngineConfiguration) {\n        this.changePlanItemStateBuilder = changePlanItemStateBuilder;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        if (changePlanItemStateBuilder.getActivatePlanItemDefinitions().size() == 0 &&\n                changePlanItemStateBuilder.getTerminatePlanItemDefinitions().size() == 0 &&\n                changePlanItemStateBuilder.getChangeToAvailableStatePlanItemDefinitions().size() == 0 &&\n                changePlanItemStateBuilder.getWaitingForRepetitionPlanItemDefinitions().size() == 0 &&\n                changePlanItemStateBuilder.getRemoveWaitingForRepetitionPlanItemDefinitions().size() == 0) {\n            \n            throw new FlowableIllegalArgumentException(\"No move plan item instance or (activate) plan item definition ids provided\");\n\n        } else if (changePlanItemStateBuilder.getCaseInstanceId() == null) {\n            throw new FlowableIllegalArgumentException(\"Case instance id is required\");   \n        }\n\n        CmmnDynamicStateManager dynamicStateManager = cmmnEngineConfiguration.getDynamicStateManager();\n        dynamicStateManager.movePlanItemInstanceState(changePlanItemStateBuilder, commandContext);\n\n        return null;\n    }\n}\n","sourceCodeStart":30,"sourceCodeEnd":57,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/ChangePlanItemStateCmd.java#L30-L57","documentation":"After confirming the builder has at least one operation, ChangePlanItemStateCmd validates that a case instance id was set. A null caseInstanceId makes the command unresolvable, so Flowable throws FlowableIllegalArgumentException(\"Case instance id is required\").","triggerScenarios":"Calling createChangePlanItemStateBuilder(null) or a ChangePlanItemStateBuilder constructed without setCaseInstanceId, then invoking changeState().","commonSituations":"Passing a variable holding the case instance id that was never resolved (null from a prior query); refactored code dropping the id parameter; building the command from a request where caseInstanceId was optional and missing.","solutions":["Pass the actual case instance id to createChangePlanItemStateBuilder(caseInstanceId).","Resolve the id first, e.g. via cmmnRuntimeService.createCaseInstanceQuery().processInstanceBusinessKey(...).singleResult().getId(), checking for null.","Add an early guard in the caller that rejects empty case instance ids with a clearer message."],"exampleFix":"// before\nString caseInstanceId = caseInstance != null ? caseInstance.getId() : null;\ncmmnRuntimeService.createChangePlanItemStateBuilder(caseInstanceId)\n    .activatePlanItemDefinition(\"task1\").changeState();\n\n// after\nif (caseInstance == null) throw new IllegalArgumentException(\"case instance not found\");\ncmmnRuntimeService.createChangePlanItemStateBuilder(caseInstance.getId())\n    .activatePlanItemDefinition(\"task1\").changeState();","handlingStrategy":"validation","validationCode":"if (caseInstanceId == null || caseInstanceId.isBlank()) throw new IllegalArgumentException(\"caseInstanceId is required for plan item state change\");","typeGuard":null,"tryCatchPattern":"try { builder.changeState(); } catch (FlowableIllegalArgumentException e) { /* missing case instance id */ }","preventionTips":["Resolve the case instance id via a query and null-check it before building the command.","Make caseInstanceId a required parameter in your service layer, never nullable.","Avoid createChangePlanItemStateBuilder(null) patterns."],"tags":["cmmn","plan-item","null","java"],"backgroundTag":"missing-required-argument","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"}