{"record":{"id":"4f7cce22847a2975","repo":"flowable/flowable-engine","slug":"can-only-complete-a-stage-plan-item-instance-that","errorCode":null,"errorMessage":"Can only complete a stage plan item instance that is marked as completable (there might still be active plan item instance).","messagePattern":"Can only complete a stage plan item instance that is marked as completable \\(there might still be active plan item instance\\)\\.","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CompleteStagePlanItemInstanceCmd.java","lineNumber":54,"sourceCode":"        super(planItemInstanceId);\n        this.force = force;\n    }\n\n    public CompleteStagePlanItemInstanceCmd(String planItemInstanceId, Map<String, Object> variables,\n            Map<String, Object> formVariables, String formOutcome, FormInfo formInfo,\n            Map<String, Object> localVariables, Map<String, Object> transientVariables, boolean force) {\n        \n        super(planItemInstanceId, variables, formVariables, formOutcome, formInfo, localVariables, transientVariables);\n        this.force = force;\n    }\n\n    @Override\n    protected void internalExecute(CommandContext commandContext, PlanItemInstanceEntity planItemInstanceEntity) {\n        if (!PlanItemDefinitionType.STAGE.equals(planItemInstanceEntity.getPlanItemDefinitionType())) {\n            throw new FlowableIllegalArgumentException(\"Can only complete plan item instances of type stage. Type is \" + planItemInstanceEntity.getPlanItemDefinitionType());\n        }\n        if (!force && !planItemInstanceEntity.isCompletable()) { // if force is true, ignore the completable flag\n            throw new FlowableIllegalArgumentException(\"Can only complete a stage plan item instance that is marked as completable (there might still be active plan item instance).\");\n        }\n        CommandContextUtil.getAgenda(commandContext).planCompletePlanItemInstanceOperation(planItemInstanceEntity);\n    }\n    \n}\n","sourceCodeStart":36,"sourceCodeEnd":60,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CompleteStagePlanItemInstanceCmd.java#L36-L60","documentation":"After the type check, CompleteStagePlanItemInstanceCmd verifies the stage is completable (no active child plan item instances) unless force=true. A stage still containing active plan items throws this FlowableIllegalArgumentException.","triggerScenarios":"Calling cmmnRuntimeService.completePlanItemInstance(stagePlanItemInstanceId, force=false) while the stage still has active child plan item instances, so planItemInstanceEntity.isCompletable() returns false.","commonSituations":"Trying to close a stage with unfinished human tasks inside; not passing the force flag in a cleanup/admin scenario; assuming completing the parent completes children.","solutions":["Complete or terminate all active child plan item instances within the stage first.","Pass force=true to cmmnRuntimeService.completePlanItemInstance(planItemInstanceId, true) if the stage should be forcibly completed.","Check children first: cmmnRuntimeService.createPlanItemInstanceQuery().planItemInstanceParentId(stageId).stateActive().count().","Adjust the case model's completion rules (auto-complete/requiring rules) if stages should close automatically."],"exampleFix":"// before\ncmmnRuntimeService.completePlanItemInstance(stageId, false); // stage has active children\n\n// after\ncmmnRuntimeService.completePlanItemInstance(stageId, true); // forced, or finish children first","handlingStrategy":"try-catch","validationCode":"long activeChildren = cmmnRuntimeService.createPlanItemInstanceQuery().planItemInstanceParentId(stageId).stateActive().count();\nboolean canComplete = activeChildren == 0;","typeGuard":null,"tryCatchPattern":"try { cmmnRuntimeService.completePlanItemInstance(stageId, false); } catch (FlowableIllegalArgumentException e) { /* stage not completable; retry with force or finish children */ }","preventionTips":["Query active child plan items before completing a stage.","Use the force=true overload only in admin/cleanup flows.","Configure stage auto-complete rules in the case model to avoid manual stage completion."],"tags":["cmmn","plan-item","stage","state","java"],"backgroundTag":"invalid-state-transition","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"}