{"record":{"id":"c1b356978d9b8379","repo":"flowable/flowable-engine","slug":"process-definition-keys-is-null","errorCode":null,"errorMessage":"Process definition keys is null","messagePattern":"Process definition keys is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java","lineNumber":444,"sourceCode":"                throw new FlowableIllegalArgumentException(\"Business key is null\");\n            }\n            \n            if (inOrStatement) {\n                this.currentOrQueryObject.businessKeyLikeIgnoreCase = processInstanceBusinessKeyLikeIgnoreCase;\n                this.currentOrQueryObject.includeChildExecutionsWithBusinessKeyQuery = includeChildExecutions;\n            } else {\n                this.businessKeyLikeIgnoreCase = processInstanceBusinessKeyLikeIgnoreCase;\n                this.includeChildExecutionsWithBusinessKeyQuery = includeChildExecutions;\n            }\n            \n            return this;\n        }\n    }\n\n    @Override\n    public ExecutionQuery processDefinitionKeys(Set<String> processDefinitionKeys) {\n        if (processDefinitionKeys == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition keys is null\");\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 ExecutionQuery excludeProcessDefinitionKeys(Set<String> excludeProcessDefinitionKeys) {\n        if (excludeProcessDefinitionKeys == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition keys is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.excludeProcessDefinitionKeys = excludeProcessDefinitionKeys;\n        } else {\n            this.excludeProcessDefinitionKeys = excludeProcessDefinitionKeys;","sourceCodeStart":426,"sourceCodeEnd":462,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java#L426-L462","documentation":"ExecutionQueryImpl.processDefinitionKeys() validates its Set<String> argument before storing it in the query. Flowable throws FlowableIllegalArgumentException immediately when the caller passes null, because a null key set cannot be translated into a SQL IN clause and silently ignoring it would produce misleading query results. The error is raised eagerly at query-building time, not when the query is executed.","triggerScenarios":"Calling executionQuery.processDefinitionKeys(null) (directly or via an or() block) on an ExecutionQuery obtained from runtimeService.createExecutionQuery().","commonSituations":"Building queries from configuration maps or REST request parameters where the 'processDefinitionKeys' field is absent/null; collecting keys into a Set that ends up empty and null due to an upstream lookup returning null instead of an empty set.","solutions":["Pass a non-null Set of process definition keys, e.g. processDefinitionKeys(Set.of(\"orderProcess\"))","If the caller has no keys, skip the processDefinitionKeys() call entirely instead of passing null","Use processDefinitionKey(String) for a single key when the set semantics are not needed","Coerce upstream nulls to an empty or default key set before building the query"],"exampleFix":"// before\nexecutionQuery.processDefinitionKeys(config.getDefinitionKeys()); // NPE-ish FlowableIllegalArgumentException when null\n// after\nSet<String> keys = config.getDefinitionKeys();\nif (keys != null && !keys.isEmpty()) {\n    executionQuery.processDefinitionKeys(keys);\n}","handlingStrategy":"validation","validationCode":"if (keys == null || keys.isEmpty()) throw new IllegalArgumentException(\"processDefinitionKeys must be a non-null, non-empty set\");\nquery.processDefinitionKeys(keys);","typeGuard":"boolean isQueryableKeySet(Set<String> s) { return s != null && !s.isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionKeys(keys);\n} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {\n    log.warn(\"Invalid processDefinitionKeys argument: {}\", e.getMessage());\n}","preventionTips":["Null-check all query filter values collected from config/REST input before applying them","Initialize collections as empty Sets, never null","Wrap query building in a small builder that skips null filters","Add unit tests exercising each query filter with a null argument"],"tags":["flowable","query-validation","null-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"}