{"record":{"id":"79aba2e96187d024","repo":"flowable/flowable-engine","slug":"set-of-process-definition-ids-is-null","errorCode":null,"errorMessage":"Set of process definition ids is null","messagePattern":"Set of process definition ids is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":420,"sourceCode":"\n    @Override\n    public ProcessInstanceQueryImpl processDefinitionId(String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition id is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionId = processDefinitionId;\n        } else {\n            this.processDefinitionId = processDefinitionId;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processDefinitionIds(Set<String> processDefinitionIds) {\n        if (processDefinitionIds == null) {\n            throw new FlowableIllegalArgumentException(\"Set of process definition ids is null\");\n        }\n        if (processDefinitionIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Set of process definition ids is empty\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionIds = processDefinitionIds;\n        } else {\n            this.processDefinitionIds = processDefinitionIds;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQueryImpl processDefinitionKey(String processDefinitionKey) {\n        if (processDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition key is null\");\n        }","sourceCodeStart":402,"sourceCodeEnd":438,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L402-L438","documentation":"ProcessInstanceQueryImpl.processDefinitionIds(Set<String>) throws FlowableIllegalArgumentException('Set of process definition ids is null') when the supplied set is null. The set feeds an IN(...) clause, which cannot be built from a null collection, so the method rejects null at query-construction time before the empty-set check and the assignment to the query or OR-query object.","triggerScenarios":"Calling .processDefinitionIds(null) — commonly when the set is built by a filter/aggregation step that returned null, a null field on a DTO, or an Optional unwrapped incorrectly.","commonSituations":"Batch dashboards where the list of visible definitions comes from user permissions and is null when permissions fail to load; code that conditionally collects ids but always calls the setter; deserialization of a request body missing the ids array.","solutions":["Null-check the set before calling processDefinitionIds and skip the filter when null","Initialize the collection to an empty (or populated) Set at declaration so it is never null","Fix the producer of the id set (permission lookup, config, deserialization) so it always returns a collection","Catch FlowableIllegalArgumentException and translate it into a client-side validation error"],"exampleFix":"// before\nSet<String> ids = loadVisibleDefinitionIds(userId); // may return null\nquery.processDefinitionIds(ids);\n\n// after\nSet<String> ids = loadVisibleDefinitionIds(userId);\nif (ids != null && !ids.isEmpty()) {\n    query.processDefinitionIds(ids);\n}","handlingStrategy":"validation","validationCode":"if (ids != null && !ids.isEmpty()) {\n    query.processDefinitionIds(ids);\n}","typeGuard":"boolean hasIds(Set<String> ids) { return ids != null && !ids.isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionIds(ids);\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"processDefinitionIds set must not be null or empty\", e);\n}","preventionTips":["Initialize id collections to an empty Set rather than leaving them null","Ensure producer methods (permission lookups, config reads) return empty collections, never null","Skip collection filters when the collection is null or empty","Test the query path with unset id collections"],"tags":["flowable","query-validation","null-check","collection-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"}