{"record":{"id":"feb185947765615f","repo":"flowable/flowable-engine","slug":"plan-item-instance-id-is-null-feb185","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/runtime/PlanItemInstanceQueryImpl.java","lineNumber":193,"sourceCode":"    }\n\n    @Override\n    public PlanItemInstanceQuery stageInstanceId(String stageInstanceId) {\n        if (stageInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Stage instance id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.stageInstanceId = stageInstanceId;\n        } else {\n            this.stageInstanceId = stageInstanceId;\n        }\n        return this;\n    }\n    \n    @Override\n    public PlanItemInstanceQuery planItemInstanceId(String planItemInstanceId) {\n        if (planItemInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Plan Item instance id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.planItemInstanceId = planItemInstanceId;\n        } else {\n            this.planItemInstanceId = planItemInstanceId;\n        }\n        return this;\n    }\n    \n    @Override\n    public PlanItemInstanceQuery planItemInstanceElementId(String elementId) {\n        if (elementId == null) {\n            throw new FlowableIllegalArgumentException(\"Element id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.elementId = elementId;\n        } else {\n            this.elementId = elementId;","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java#L175-L211","documentation":"Flowable's PlanItemInstanceQuery.planItemInstanceId() throws FlowableIllegalArgumentException when planItemInstanceId is null. This filter targets a single plan item instance by its runtime id; null is rejected immediately in the setter. To query plan items by definition or element instead, use the corresponding filter methods.","triggerScenarios":"Calling planItemInstanceId(null) — typically when a variable, message payload, or REST parameter holding the plan item instance id was never set, or when completing/triggering code passes a null id into a helper that builds the query.","commonSituations":"Custom event/job handlers reading ids from variables that weren't set; REST endpoints with missing path segments; copying listener code where the passed variable name changed between Flowable versions.","solutions":["Pass the actual plan item instance id (e.g. planItemInstance.getId() from a trigger/complete callback)","Guard: only apply the filter when the id is non-null","Verify variable/payload keys — a typo in the variable name silently yields null"],"exampleFix":"// before\nplanItemInstanceQuery.planItemInstanceId((String) execution.getVariable(\"planItemId\"));\n\n// after\nString planItemId = (String) execution.getVariable(\"planItemId\");\nif (planItemId != null) {\n    planItemInstanceQuery.planItemInstanceId(planItemId);\n}","handlingStrategy":"validation","validationCode":"String planItemId = (String) execution.getVariable(\"planItemId\");\nif (planItemId != null) {\n    query.planItemInstanceId(planItemId);\n}","typeGuard":"String asString(Object v) { return v instanceof String s && !s.isBlank() ? s : null; }","tryCatchPattern":"try {\n    query.planItemInstanceId(planItemId);\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"planItemInstanceId is required\", e);\n}","preventionTips":["Verify variable names/keys — a typo silently yields null from getVariable()","Prefer typed accessors and null-checks when reading ids from variables or payloads","Validate listener/job payload fields before constructing queries"],"tags":["flowable","cmmn","query","null-argument"],"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"}