{"record":{"id":"88c82f1d953b3c64","repo":"flowable/flowable-engine","slug":"parentscopeid-is-null-88c82f","errorCode":null,"errorMessage":"parentScopeId is null","messagePattern":"parentScopeId is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceQueryImpl.java","lineNumber":399,"sourceCode":"    }\n\n    @Override\n    public CaseInstanceQuery caseInstanceRootScopeIds(Set<String> rootScopeIds) {\n        if (rootScopeIds == null || rootScopeIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"rootScopeIds is null or empty\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.rootScopeIds = rootScopeIds;\n        } else {\n            this.rootScopeIds = rootScopeIds;\n        }\n        return this;\n    }\n\n    @Override\n    public CaseInstanceQuery caseInstanceParentScopeId(String parentScopeId) {\n        if (parentScopeId == null) {\n            throw new FlowableIllegalArgumentException(\"parentScopeId is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.parentScopeId = parentScopeId;\n        } else {\n            this.parentScopeId = parentScopeId;\n        }\n        return this;\n    }\n\n    @Override\n    public CaseInstanceQuery caseInstanceParentScopeIds(Set<String> parentScopeIds) {\n        if (parentScopeIds == null || parentScopeIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"parentScopeIds is null or empty\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.parentScopeIds = parentScopeIds;\n        } else {\n            this.parentScopeIds = parentScopeIds;","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceQueryImpl.java#L381-L417","documentation":"Flowable's CaseInstanceQueryImpl throws FlowableIllegalArgumentException when caseInstanceParentScopeId(String) is called with null. A parent scope id filters case instances whose parent (e.g. a containing plan item or process scope) has the given id; null is not a meaningful filter value, so the API rejects it eagerly. Use a dedicated 'no parent' query path if that is the intent.","triggerScenarios":"Calling caseInstanceParentScopeId(null) directly, or passing a variable holding the parent scope id that was never populated (lookup of the parent plan item/execution returned null).","commonSituations":"Resolving a parent scope from a runtime activity/plan-item that has already completed or not yet started; misreading which id to pass (passing case instance id vs scope id); dynamic query builders that forward nullable request parameters unfiltered.","solutions":["Verify the parent scope id lookup actually returns a value before building the query; only add the criterion when the id is non-null","Confirm you are passing the correct scope id (parent scope of the case instance, not the case instance id itself)","If 'any parent' is intended, omit the parentScopeId criterion entirely","If 'no parent' is intended, use caseInstanceWithoutParentScopeId / the appropriate no-parent API instead of null"],"exampleFix":"// before\nquery.caseInstanceParentScopeId(parentScopeId); // parentScopeId may be null\n// after\nif (parentScopeId != null) {\n    query.caseInstanceParentScopeId(parentScopeId);\n}","handlingStrategy":"validation","validationCode":"if (parentScopeId == null || parentScopeId.isBlank()) {\n    throw new IllegalArgumentException(\"parentScopeId must be provided\");\n}\nquery.caseInstanceParentScopeId(parentScopeId);","typeGuard":"boolean hasText(String s) {\n    return s != null && !s.trim().isEmpty();\n}","tryCatchPattern":"try {\n    query.caseInstanceParentScopeId(parentScopeId);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"parentScopeId was null: {}\", e.getMessage());\n    query = runtimeService.createCaseInstanceQuery(); // rebuild without the filter\n}","preventionTips":["Resolve and assert the parent scope id before building the query","Never pass null to single-value Flowable query filters; omit the criterion instead","Distinguish 'no filter' from 'filter by null' in your query builder API","Verify which id type the method expects (scope id, not case instance id)"],"tags":["flowable","cmmn","query","null-check","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-14T05:17:10.506Z"}