{"record":{"id":"673ac82403be99aa","repo":"flowable/flowable-engine","slug":"plan-item-instance-id-is-null","errorCode":null,"errorMessage":"Plan item instance id is null","messagePattern":"Plan item instance id is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/AbstractNeedsPlanItemInstanceCmd.java","lineNumber":64,"sourceCode":"    }\n\n    public AbstractNeedsPlanItemInstanceCmd(String planItemInstanceId, Map<String, Object> variables,\n            Map<String, Object> formVariables, String formOutcome, FormInfo formInfo,\n            Map<String, Object> localVariables, Map<String, Object> transientVariables) {\n        \n        this.planItemInstanceId = planItemInstanceId;\n        this.variables = variables;\n        this.formVariables = formVariables;\n        this.formOutcome = formOutcome;\n        this.formInfo = formInfo;\n        this.localVariables = localVariables;\n        this.transientVariables = transientVariables;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        if (planItemInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Plan item instance id is null\");\n        }\n\n        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);\n        PlanItemInstanceEntity planItemInstanceEntity = cmmnEngineConfiguration.getPlanItemInstanceEntityManager().findById(planItemInstanceId);\n        if (planItemInstanceEntity == null) {\n            throw new FlowableObjectNotFoundException(\"Cannot find plan item instance for id \" + planItemInstanceId, PlanItemInstanceEntity.class);\n        }\n\n        if (formInfo != null) {\n            FormService formService = CommandContextUtil.getFormService(commandContext);\n            if (formService == null) {\n                throw new FlowableIllegalStateException(\"Form engine is not initialized\");\n            }\n\n            Map<String, Object> variablesFromFormSubmission = formService.getVariablesFromFormSubmission(planItemInstanceEntity.getPlanItemDefinitionId(), \n                    planItemInstanceEntity.getPlanItemDefinitionType(), planItemInstanceEntity.getCaseInstanceId(), planItemInstanceEntity.getCaseDefinitionId(), \n                    ScopeTypes.CMMN, formInfo, formVariables, formOutcome);\n","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/AbstractNeedsPlanItemInstanceCmd.java#L46-L82","documentation":"FlowableIllegalArgumentException thrown in AbstractNeedsPlanItemInstanceCmd.execute when planItemInstanceId is null. The command validates the required id before doing any engine work because a null id cannot identify a plan item instance. Concrete commands (completing plan items with/without forms) inherit this check.","triggerScenarios":"Calling cmmnTaskService methods such as completePlanItemPlanForm or completePlanItemStandaloneForm with a null planItemInstanceId; id variable never set from a previous query; request body missing the plan item id field.","commonSituations":"REST endpoints where planItemInstanceId came from an optional field that was absent; front-end sent null for an unstarted plan item; code deriving the id from another entity that returned null.","solutions":["Validate the planItemInstanceId non-null/non-empty before calling the task service","Ensure the UI/API caller always supplies the plan item id obtained from plan item instance queries","Check the upstream query that produced the id for null results","Use the correct API overload where the id is a required parameter"],"exampleFix":"// before\ncmmnTaskService.completePlanItemPlanForm(planItemInstanceId, caseInstanceId, formInfo, variables, null);\n// after\nObjects.requireNonNull(planItemInstanceId, \"planItemInstanceId is required\");\ncmmnTaskService.completePlanItemPlanForm(planItemInstanceId, caseInstanceId, formInfo, variables, null);","handlingStrategy":"validation","validationCode":"if (planItemInstanceId == null || planItemInstanceId.isBlank()) throw new IllegalArgumentException(\"planItemInstanceId is required\");","typeGuard":"boolean hasPlanItemInstanceId(String id) { return id != null && !id.isBlank(); }","tryCatchPattern":"try { cmmnTaskService.completePlanItemPlanForm(...); }\ncatch (FlowableIllegalArgumentException e) { log.error(\"Missing/invalid planItemInstanceId: {}\", e.getMessage()); }","preventionTips":["Reject requests missing the plan item id before hitting the engine","Obtain planItemInstanceId from plan item instance queries, not free-form input","Use Objects.requireNonNull when wiring ids into commands","Guard against null-producing upstream queries with Optional"],"tags":["flowable","cmmn","null-argument","plan-item"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}