{"record":{"id":"e720008aeddaa17d","repo":"flowable/flowable-engine","slug":"stage-instance-id-is-null","errorCode":null,"errorMessage":"Stage instance id is null","messagePattern":"Stage 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":180,"sourceCode":"        if (caseInstanceIds == null) {\n            throw new FlowableIllegalArgumentException(\"Set of case instance ids is null\");\n        }\n        if (caseInstanceIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Set of case instance ids is empty\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.caseInstanceIds = caseInstanceIds;\n        } else {\n            this.caseInstanceIds = caseInstanceIds;\n        }\n        return this;\n    }\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;","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java#L162-L198","documentation":"Flowable's PlanItemInstanceQuery.stageInstanceId() throws FlowableIllegalArgumentException when stageInstanceId is null. This filter narrows plan item instances to those inside a specific stage; the setter validates the argument eagerly so malformed queries never reach the database.","triggerScenarios":"Calling stageInstanceId(null), e.g. when the stage instance id comes from a plan item lookup that returned null, an unset variable, or an absent request parameter.","commonSituations":"Navigating a case hierarchy where the code assumes a parent stage exists; querying at case root level where no stage is active; UI code passing a cleared selection field.","solutions":["Pass a valid stage instance id (resolve it via PlanItemRuntimeService for the stage plan item)","Only call stageInstanceId(id) when the id is non-null; at root level, omit the filter","Null-check the PlanItemInstance representing the stage before using its getId()"],"exampleFix":"// before\nquery.stageInstanceId(stage.getId()); // stage may be null\n\n// after\nif (stage != null) {\n    query.stageInstanceId(stage.getId());\n}","handlingStrategy":"validation","validationCode":"if (stageInstanceId != null && !stageInstanceId.isBlank()) {\n    query.stageInstanceId(stageInstanceId);\n}","typeGuard":"boolean isPresent(String id) { return id != null && !id.isBlank(); }","tryCatchPattern":"try {\n    query.stageInstanceId(stageInstanceId);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Stage filter skipped: {}\", e.getMessage());\n}","preventionTips":["Null-check the stage PlanItemInstance before using its id as a filter","Handle the 'no active stage' case explicitly in case navigation code","Nullify UI selections into 'no filter' rather than null ids reaching the query"],"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"}