{"record":{"id":"7dbd4e2bcb1ca549","repo":"flowable/flowable-engine","slug":"planiteminstanceid-is-null-7dbd4e","errorCode":null,"errorMessage":"planItemInstanceId is null","messagePattern":"planItemInstanceId is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/SetLocalVariableCmd.java","lineNumber":40,"sourceCode":"/**\n * @author Tijs Rademakers\n */\npublic class SetLocalVariableCmd implements Command<Void> {\n    \n    protected String planItemInstanceId;\n    protected String variableName;\n    protected Object variableValue;\n    \n    public SetLocalVariableCmd(String planItemInstanceId, String variableName, Object variableValue) {\n        this.planItemInstanceId = planItemInstanceId;\n        this.variableName = variableName;\n        this.variableValue = variableValue;\n    }\n    \n    @Override\n    public Void execute(CommandContext commandContext) {\n        if (planItemInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"planItemInstanceId is null\");\n        }\n        if (variableName == null) {\n            throw new FlowableIllegalArgumentException(\"variable name is null\");\n        }\n     \n        PlanItemInstanceEntity planItemInstanceEntity = CommandContextUtil.getPlanItemInstanceEntityManager(commandContext).findById(planItemInstanceId);\n        if (planItemInstanceEntity == null) {\n            throw new FlowableObjectNotFoundException(\"No plan item instance found for id \" + planItemInstanceId, PlanItemInstanceEntity.class);\n        }\n        planItemInstanceEntity.setVariableLocal(variableName, variableValue);\n        \n        CommandContextUtil.getAgenda(commandContext).planEvaluateCriteriaOperation(planItemInstanceEntity.getCaseInstanceId());\n        \n        return null;\n    }\n\n}\n","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/SetLocalVariableCmd.java#L22-L58","documentation":"SetLocalVariableCmd.execute() validates its inputs before touching the engine. If the planItemInstanceId passed to the set local variable command is null, it throws FlowableIllegalArgumentException immediately, since no plan item instance row can be looked up without an id. This is a fail-fast guard against a programming or API-usage mistake.","triggerScenarios":"Calling CmmnRuntimeService.setLocalVariable(String planItemInstanceId, String variableName, Object value) (or any path that schedules SetLocalVariableCmd) with a null planItemInstanceId, e.g. a variable holding a plan item id that was never assigned or was lost upstream.","commonSituations":"Developers resolve the plan item id from a map/query result that returned null, pass a variable that failed initialization, or build the command programmatically in custom jobs/listeners where the id field is optional in their model but required by the engine.","solutions":["Check where the planItemInstanceId value comes from and fix the code so it is populated before calling setLocalVariable.","Add a null/blank check or Objects.requireNonNull on the id at your call site to fail with a clearer message.","If the id is genuinely unknown, first look up the plan item instance (e.g. createPlanItemInstanceQuery().planItemInstanceCaseInstanceId(...)) and use its id."],"exampleFix":"// before\ncmmnRuntimeService.setLocalVariable(planItemId, \"status\", value); // planItemId may be null\n// after\nObjects.requireNonNull(planItemId, \"planItemId must be resolved before setting a local variable\");\ncmmnRuntimeService.setLocalVariable(planItemId, \"status\", value);","handlingStrategy":"validation","validationCode":"if (planItemInstanceId == null || planItemInstanceId.isEmpty()) {\n    throw new IllegalArgumentException(\"planItemInstanceId is required before calling setLocalVariable\");\n}","typeGuard":"boolean hasPlanItemId(String id) { return id != null && !id.isEmpty(); }","tryCatchPattern":"try {\n    cmmnRuntimeService.setLocalVariable(planItemId, name, value);\n} catch (FlowableIllegalArgumentException e) {\n    log.error(\"Invalid argument for setLocalVariable: {}\", e.getMessage());\n}","preventionTips":["Resolve plan item ids via createPlanItemInstanceQuery() rather than manual state.","Use Objects.requireNonNull on ids at API boundaries in your own code.","Never store nullable ids for later engine calls; fail at the point of creation."],"tags":["cmmn","null-argument","validation"],"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"}