{"record":{"id":"69aff0e1236134ba","repo":"flowable/flowable-engine","slug":"the-plan-item-must-be-provided-when-creating-a-new","errorCode":null,"errorMessage":"The plan item must be provided when creating a new plan item instance","messagePattern":"The plan item must be provided when creating a new plan item instance","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/persistence/entity/PlanItemInstanceEntityBuilderImpl.java","lineNumber":136,"sourceCode":"    public String getTenantId() {\n        return tenantId;\n    }\n    public Map<String, Object> getLocalVariables() {\n        return localVariables;\n    }\n    public boolean hasLocalVariables() {\n        return localVariables != null && localVariables.size() > 0;\n    }\n    public boolean isAddToParent() {\n        return addToParent;\n    }\n    public boolean isSilentNameExpressionEvaluation() {\n        return silentNameExpressionEvaluation;\n    }\n\n    protected void validateData() {\n        if (planItem == null) {\n            throw new FlowableIllegalArgumentException(\"The plan item must be provided when creating a new plan item instance\");\n        }\n        if (caseDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"The case definition id must be provided when creating a new plan item instance\");\n        }\n        if (caseInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"The case instance id must be provided when creating a new plan item instance\");\n        }\n    }\n}\n","sourceCodeStart":118,"sourceCodeEnd":146,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/persistence/entity/PlanItemInstanceEntityBuilderImpl.java#L118-L146","documentation":"PlanItemInstanceEntityBuilderImpl.create() calls validateData() before creating a PlanItemInstanceEntity. The planItem field is mandatory — without it the engine cannot instantiate the plan item instance — so a null planItem yields this FlowableIllegalArgumentException.","triggerScenarios":"Building a plan item instance via PlanItemInstanceEntityBuilderImpl (e.g. createPlanItemInstanceBuilder()) and calling create() without ever setting planItem(...).","commonSituations":"Custom engine extensions/tests constructing plan item instances programmatically; partial builder configuration copied from other builders; forgetting the builder call chain before create().","solutions":["Set the plan item on the builder before create(): builder.planItem(planItem).","Ensure the PlanItem is resolved from the CaseDefinition's CmmnModel before building the instance.","Review custom code that builds plan item instances and add the missing planItem(...) call."],"exampleFix":"// before\ncmmnRuntimeService.createPlanItemInstanceBuilder()\n    .caseDefinitionId(defId).caseInstanceId(instId).create();\n// after\ncmmnRuntimeService.createPlanItemInstanceBuilder()\n    .planItem(planItem).caseDefinitionId(defId).caseInstanceId(instId).create();","handlingStrategy":"validation","validationCode":"if (planItem == null) throw new IllegalArgumentException(\"planItem is required before create()\");","typeGuard":"boolean canCreate = builder != null && planItem != null && caseDefinitionId != null && caseInstanceId != null;","tryCatchPattern":"try { entity = builder.create(); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().contains(\"plan item must be provided\")) { /* set planItem(...) */ } throw e; }","preventionTips":["Always set planItem first in the builder chain.","Resolve the PlanItem from the CmmnModel of the case definition before building.","Wrap builder creation in helper methods that enforce required fields.","Cover builder usage with unit tests asserting preconditions."],"tags":["cmmn","builder","validation","plan-item-instance"],"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-18T11:17:12.947Z"}