{"record":{"id":"68aea1b6851c5251","repo":"flowable/flowable-engine","slug":"rootscopeids-is-null-or-empty-68aea1","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/HistoricProcessInstanceQueryImpl.java","lineNumber":378,"sourceCode":"            this.businessStatusLikeIgnoreCase = businessStatusLikeIgnoreCase;\n        }\n        return this;\n    }\n\n    @Override\n    public HistoricProcessInstanceQuery processInstanceRootScopeId(String rootScopeId) {\n        if (inOrStatement) {\n            this.currentOrQueryObject.rootScopeId = rootScopeId;\n        } else {\n            this.rootScopeId = rootScopeId;\n        }\n        return this;\n    }\n\n    @Override\n    public HistoricProcessInstanceQuery 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 HistoricProcessInstanceQuery processInstanceParentScopeId(String parentId) {\n        if (inOrStatement) {\n            this.currentOrQueryObject.parentScopeId = parentId;\n        } else {\n            this.parentScopeId = parentId;\n        }\n        return this;\n    }","sourceCodeStart":360,"sourceCodeEnd":396,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/HistoricProcessInstanceQueryImpl.java#L360-L396","documentation":"HistoricProcessInstanceQuery.processInstanceRootScopeIds(Set<String>) requires a non-null, non-empty set of root scope ids. Flowable throws FlowableIllegalArgumentException when rootScopeIds is null or empty because the resulting SQL IN filter would be undefined. Validation happens eagerly when building the query.","triggerScenarios":"Calling processInstanceRootScopeIds(rootScopeIds) with a null set or an empty set (new HashSet<>(), or a collection emptied by prior filtering).","commonSituations":"Hierarchical process-instance queries where the parent/root scope ids come from an optional API parameter or a lookup that returned nothing; copy-paste from processInstanceIds calls without guarding null/empty.","solutions":["Ensure the set contains at least one root scope id before calling","Guard with a null/isEmpty check and skip the criterion or use a different query path when absent","Return an empty result early if no root scope ids are applicable","Verify the id source (parent instance lookup) actually resolves values"],"exampleFix":"// before\nquery.processInstanceRootScopeIds(rootScopeIds); // throws when null or empty\n// after\nif (rootScopeIds != null && !rootScopeIds.isEmpty()) {\n    query.processInstanceRootScopeIds(rootScopeIds);\n}","handlingStrategy":"validation","validationCode":"if (rootScopeIds == null || rootScopeIds.isEmpty()) {\n    throw new IllegalArgumentException(\"rootScopeIds must be non-null and non-empty\");\n}\nquery.processInstanceRootScopeIds(rootScopeIds);","typeGuard":"boolean isValidScopeIds(Set<String> ids) {\n    return ids != null && !ids.isEmpty();\n}","tryCatchPattern":"try {\n    query.processInstanceRootScopeIds(rootScopeIds);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Skipping root scope filter: {}\", e.getMessage());\n    // continue with query minus this criterion\n}","preventionTips":["Validate scope-id sets at the API boundary before building queries","Null- and size-check collections in one predicate helper","Ensure parent/scope resolution code never returns null collections","Add tests for hierarchy query builders with missing scope ids"],"tags":["flowable","null-check","empty-collection","query-validation"],"backgroundTag":"missing-required-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"}