{"record":{"id":"bd972c9b182b1c8c","repo":"flowable/flowable-engine","slug":"set-of-process-definition-keys-is-null","errorCode":null,"errorMessage":"Set of process definition keys is null","messagePattern":"Set of process definition keys is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":479,"sourceCode":"    \n    @Override\n    public ProcessInstanceQueryImpl processDefinitionKeyLikeIgnoreCase(String processDefinitionKeyLikeIgnoreCase) {\n        if (processDefinitionKeyLikeIgnoreCase == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition key is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionKeyLikeIgnoreCase = processDefinitionKeyLikeIgnoreCase;\n        } else {\n            this.processDefinitionKeyLikeIgnoreCase = processDefinitionKeyLikeIgnoreCase;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processDefinitionKeys(Set<String> processDefinitionKeys) {\n        if (processDefinitionKeys == null) {\n            throw new FlowableIllegalArgumentException(\"Set of process definition keys is null\");\n        }\n        if (processDefinitionKeys.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Set of process definition keys is empty\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionKeys = processDefinitionKeys;\n        } else {\n            this.processDefinitionKeys = processDefinitionKeys;\n        }\n        return this;\n    }\n    \n    @Override\n    public ProcessInstanceQuery excludeProcessDefinitionKeys(Set<String> excludeProcessDefinitionKeys) {\n        if (excludeProcessDefinitionKeys == null) {\n            throw new FlowableIllegalArgumentException(\"Set of process definition keys is null\");\n        }","sourceCodeStart":461,"sourceCodeEnd":497,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L461-L497","documentation":"Flowable's ProcessInstanceQuery.processDefinitionKeys(Set<String>) throws FlowableIllegalArgumentException when the passed set is null. The API requires an actual, non-empty set of process definition keys to build the query condition. Throwing eagerly at query-construction time surfaces the bad argument immediately instead of failing later at query execution.","triggerScenarios":"Calling processInstanceQuery().processDefinitionKeys(null), e.g. when the set comes from a variable, method parameter, or configuration value that was never initialized.","commonSituations":"Dynamic query builders that assemble key sets from user input or config; refactors where a default set assignment was removed; deserialized DTOs with a null field passed straight into the query.","solutions":["Ensure the Set<String> is initialized before calling processDefinitionKeys (e.g. new HashSet<>(Arrays.asList(\"key1\",\"key2\"))).","Check the upstream code path producing the set and default it to an empty guard that skips the filter instead of passing null.","Wrap the call with a null check and skip the filter condition when the set is absent.","Catch FlowableIllegalArgumentException around the query construction and log/propagate a clear client-side message."],"exampleFix":"// before\nSet<String> keys = getConfiguredKeys(); // may be null\nruntimeService.createProcessInstanceQuery().processDefinitionKeys(keys);\n// after\nSet<String> keys = getConfiguredKeys();\nif (keys != null && !keys.isEmpty()) {\n    runtimeService.createProcessInstanceQuery().processDefinitionKeys(keys);\n}","handlingStrategy":"validation","validationCode":"if (keys == null || keys.isEmpty()) { throw new IllegalArgumentException(\"processDefinitionKeys must be a non-empty set\"); }\nruntimeService.createProcessInstanceQuery().processDefinitionKeys(keys);","typeGuard":"boolean isValidKeySet(Set<String> s) { return s != null && !s.isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionKeys(keys);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Invalid processDefinitionKeys argument: {}\", e.getMessage());\n    throw new BadRequestException(e.getMessage());\n}","preventionTips":["Initialize collection fields to empty sets, never null, in DTOs and config beans.","Apply query filters conditionally: only call the setter when the collection is non-empty.","Centralize Flowable query building in helpers that enforce argument validation once.","Add unit tests covering null/empty query argument paths."],"tags":["flowable","null-argument","query-api","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-18T11:17:12.947Z"}