{"record":{"id":"a92143685c02dae9","repo":"flowable/flowable-engine","slug":"process-definition-key-is-null","errorCode":null,"errorMessage":"Process definition key is null","messagePattern":"Process definition key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java","lineNumber":156,"sourceCode":"    }\n\n    @Override\n    public ExecutionQueryImpl processDefinitionId(String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition id is null\");\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 ExecutionQueryImpl processDefinitionKey(String processDefinitionKey) {\n        if (processDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;\n        } else {\n            this.processDefinitionKey = processDefinitionKey;\n        }\n        return this;\n    }\n    \n    @Override\n    public ExecutionQueryImpl processDefinitionKeyLike(String processDefinitionKeyLike) {\n        if (processDefinitionKeyLike == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionKeyLike = processDefinitionKeyLike;\n        } else {\n            this.processDefinitionKeyLike = processDefinitionKeyLike;","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java#L138-L174","documentation":"ExecutionQuery.processDefinitionKey() requires a non-null key; Flowable throws FlowableIllegalArgumentException because null would mean 'no filter'. Works identically inside OR statements via currentOrQueryObject.","triggerScenarios":"Calling executionQuery.processDefinitionKey(null) with a key sourced from nullable config, message payload, or unresolved variable.","commonSituations":"Filtering executions for a business process whose key wasn't provided by the caller; mapping optional DTO fields unconditionally; environment-specific config missing the key.","solutions":["Pass a non-null process definition key","Conditionally apply the filter only when the key is present","Ensure the key is resolved/validated before building the query"],"exampleFix":"// before\nexecutionQuery.processDefinitionKey(payload.getProcessKey());\n// after\nif (payload.getProcessKey() != null) {\n    executionQuery.processDefinitionKey(payload.getProcessKey());\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionKey == null || processDefinitionKey.isEmpty()) {\n    throw new IllegalArgumentException(\"processDefinitionKey is required\");\n}\nquery.processDefinitionKey(processDefinitionKey);","typeGuard":"boolean hasDefinitionKey(String key) { return key != null && !key.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionKey(key);\n} catch (FlowableIllegalArgumentException e) {\n    logger.warn(\"Missing process definition key for execution query\", e);\n}","preventionTips":["Make the key a required, validated request field when the filter is mandatory","Skip the setter for optional keys instead of passing null","Keep a single query-builder utility that enforces null guards"],"tags":["query","null-argument","execution"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T16:30:33.424Z"}