{"record":{"id":"b393e6fd5dd7728d","repo":"flowable/flowable-engine","slug":"rootscopeids-is-null-or-empty-b393e6","errorCode":null,"errorMessage":"rootScopeIds is null or empty","messagePattern":"rootScopeIds is null or empty","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":718,"sourceCode":"            this.nameLikeIgnoreCase = nameLikeIgnoreCase.toLowerCase();\n        }\n        return this;\n    }\n    \n    @Override\n    public ProcessInstanceQuery processInstanceRootScopeId(String rootId) {\n        if (inOrStatement) {\n            this.currentOrQueryObject.rootScopeId = rootId;\n        } else {\n            this.rootScopeId = rootId;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processInstanceRootScopeIds(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 ProcessInstanceQuery processInstanceParentScopeId(String parentId) {\n        if (inOrStatement) {\n            this.currentOrQueryObject.parentScopeId = parentId;\n        } else {\n            this.parentScopeId = parentId;\n        }\n        return this;\n    }","sourceCodeStart":700,"sourceCodeEnd":736,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L700-L736","documentation":"ProcessInstanceQueryImpl.processInstanceRootScopeIds(Set<String>) filters process instances by their root scope IDs. Flowable throws FlowableIllegalArgumentException for a null or empty set because an empty ID set cannot select any instances and would produce broken SQL (empty IN clause). The library fails fast at query-construction time.","triggerScenarios":"Calling processInstanceRootScopeIds(null) or with an empty set, typically when root scope IDs were collected dynamically (e.g., from parent instances or case roots) and none were found.","commonSituations":"Batch jobs computing root scope IDs from another query that returned no rows; multi-instance/standalone-deployment setups where root scope tracking isn't populated; copy-paste from processInstanceCallbackIds with wrong variable populated.","solutions":["Only call processInstanceRootScopeIds when the set is non-empty; skip the filter otherwise","Populate the set with valid root scope IDs retrieved from the instances you intend to filter on","Fix the upstream lookup that produces an empty ID set","Catch FlowableIllegalArgumentException and return an empty result intentionally if an empty set genuinely means 'nothing to query'"],"exampleFix":"// before\nquery.processInstanceRootScopeIds(rootScopeIds);\n// after\nif (rootScopeIds != null && !rootScopeIds.isEmpty()) {\n    query.processInstanceRootScopeIds(rootScopeIds);\n} else {\n    // no roots to filter on; return empty result or skip filter\n}","handlingStrategy":"validation","validationCode":"if (rootScopeIds == null || rootScopeIds.isEmpty()) {\n    throw new IllegalArgumentException(\"At least one root scope id is required\");\n}","typeGuard":"boolean hasRootScopeIds = rootScopeIds != null && !rootScopeIds.isEmpty();","tryCatchPattern":"try {\n    query.processInstanceRootScopeIds(rootScopeIds);\n} catch (FlowableIllegalArgumentException e) {\n    // return empty result or omit the filter\n}","preventionTips":["Guard all Set-based ID filters before applying them","Verify upstream ID collection queries actually returned rows","Handle the 'no roots found' case as business logic, not as an empty filter"],"tags":["flowable","process-instance-query","empty-collection","scope-ids"],"backgroundTag":"empty-required-field","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"}