{"record":{"id":"b8b28a15e8fac8e2","repo":"flowable/flowable-engine","slug":"set-of-process-instance-ids-is-null-b8b28a","errorCode":null,"errorMessage":"Set of process instance ids is null","messagePattern":"Set of process instance ids is null","errorType":"validation","errorClass":"ActivitiIllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/HistoricProcessInstanceQueryImpl.java","lineNumber":107,"sourceCode":"\n    public HistoricProcessInstanceQueryImpl(CommandExecutor commandExecutor) {\n        super(commandExecutor);\n    }\n\n    @Override\n    public HistoricProcessInstanceQueryImpl processInstanceId(String processInstanceId) {\n        if (inOrStatement) {\n            this.currentOrQueryObject.processInstanceId = processInstanceId;\n        } else {\n            this.processInstanceId = processInstanceId;\n        }\n        return this;\n    }\n\n    @Override\n    public HistoricProcessInstanceQuery processInstanceIds(Set<String> processInstanceIds) {\n        if (processInstanceIds == null) {\n            throw new ActivitiIllegalArgumentException(\"Set of process instance ids is null\");\n        }\n        if (processInstanceIds.isEmpty()) {\n            throw new ActivitiIllegalArgumentException(\"Set of process instance ids is empty\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processInstanceIds = processInstanceIds;\n        } else {\n            this.processInstanceIds = processInstanceIds;\n        }\n        return this;\n    }\n\n    @Override\n    public HistoricProcessInstanceQueryImpl processDefinitionId(String processDefinitionId) {\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionId = processDefinitionId;\n        } else {","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/HistoricProcessInstanceQueryImpl.java#L89-L125","documentation":"HistoricProcessInstanceQuery.processInstanceIds(Set<String>) requires a non-null set of process instance ids to filter history by. The library throws ActivitiIllegalArgumentException when the set is null, since an IN-clause filter needs an explicit collection. An empty set is rejected separately (see the 'is empty' error).","triggerScenarios":"Calling processInstanceIds(null), typically when the set is the result of an upstream lookup that returned nothing or a field that was never initialized.","commonSituations":"Collecting ids from a previous query whose result was null/absent; deserialized request payloads missing the ids field; service-to-service calls where the collection was lost in mapping.","solutions":["Ensure the set is populated before calling, e.g. new HashSet<>(Arrays.asList(\"id1\",\"id2\")).","If the id list may be empty, skip applying the filter entirely instead of passing null.","Null-check at the call site and throw a domain-specific error naming the missing data.","Fix the upstream lookup that produced null instead of an empty collection."],"exampleFix":"// before\nSet<String> ids = null;\nquery.processInstanceIds(ids);\n// after\nSet<String> ids = collectProcessInstanceIds();\nif (ids != null && !ids.isEmpty()) {\n    query.processInstanceIds(ids);\n}","handlingStrategy":"validation","validationCode":"if (ids == null) throw new IllegalArgumentException(\"processInstanceIds required\");\nif (ids.isEmpty()) { /* skip filter or return empty result */ }","typeGuard":"boolean hasIds(java.util.Collection<?> c) { return c != null && !c.isEmpty(); }","tryCatchPattern":"try {\n    query.processInstanceIds(ids);\n} catch (ActivitiIllegalArgumentException e) {\n    if (e.getMessage().contains(\"is null\")) {\n        throw new IllegalStateException(\"Caller bug: null id set\", e);\n    }\n}","preventionTips":["Return empty collections, never null, from id-producing methods.","Skip the filter when the collection is empty instead of passing null.","Null-check upstream lookup results before chaining.","Add null-checks at deserialization boundaries (MapStruct/Jackson)."],"tags":["java","activiti","query","null-argument","collection"],"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"}