{"record":{"id":"6eba196babcc1d41","repo":"flowable/flowable-engine","slug":"set-of-process-instance-ids-is-null-6eba19","errorCode":null,"errorMessage":"Set of process instance ids is null","messagePattern":"Set of process instance ids is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/HistoricProcessInstanceQueryImpl.java","lineNumber":161,"sourceCode":"    public HistoricProcessInstanceQueryImpl(CommandExecutor commandExecutor, ProcessEngineConfigurationImpl processEngineConfiguration) {\n        super(commandExecutor, processEngineConfiguration.getVariableServiceConfiguration());\n        this.processEngineConfiguration = processEngineConfiguration;\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 FlowableIllegalArgumentException(\"Set of process instance ids is null\");\n        }\n        if (processInstanceIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"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":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/HistoricProcessInstanceQueryImpl.java#L143-L179","documentation":"Flowable's HistoricProcessInstanceQuery.processInstanceIds(Set<String>) requires a non-null set of process instance ids. The API throws FlowableIllegalArgumentException immediately at query-build time when the argument is null, rather than failing later at query execution. This fail-fast validation prevents building a query with an undefined id filter.","triggerScenarios":"Calling historicProcessInstanceQuery().processInstanceIds(ids) where ids is null — e.g. a caller passes an uninitialized variable, a method returns null instead of a set, or a null is forwarded from an upstream parameter.","commonSituations":"Building dynamic queries where the id set comes from an optional request parameter, a collection lookup that returned null, or refactoring that changed an empty-set default into null.","solutions":["Initialize the set before calling processInstanceIds, e.g. Set<String> ids = new HashSet<>(...);","Skip the processInstanceIds call (or use a fallback filter) when the collection is null","Guard with a null check or Objects.requireNonNullElse(ids, Collections.emptySet()) and only apply the filter when non-empty","If the set may legitimately be empty, handle the empty case separately (empty sets also throw, see error 1921)"],"exampleFix":"// before\nquery.processInstanceIds(ids); // NPE-prone / throws when ids == null\n// after\nif (ids != null && !ids.isEmpty()) {\n    query.processInstanceIds(ids);\n}","handlingStrategy":"validation","validationCode":"if (ids == null) {\n    throw new IllegalArgumentException(\"processInstanceIds must be non-null before building the query\");\n}\nquery.processInstanceIds(ids);","typeGuard":"boolean isValidIdSet(Set<String> ids) {\n    return ids != null;\n}","tryCatchPattern":"try {\n    query.processInstanceIds(ids);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"null\")) {\n        ids = Collections.emptySet(); // handle missing ids explicitly\n    } else {\n        throw e;\n    }\n}","preventionTips":["Never pass nullable collections straight into Flowable query builder methods","Centralize query building in a helper that validates arguments once","Prefer Optional<Set<String>> for optional id sets and unwrap with orElseThrow","Return empty-set (not null) from methods that collect ids"],"tags":["flowable","null-check","query-validation","java"],"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"}