{"record":{"id":"89a5dbef57d6cc0c","repo":"flowable/flowable-engine","slug":"process-definition-key-is-null-89a5db","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/ProcessInstanceQueryImpl.java","lineNumber":437,"sourceCode":"        if (processDefinitionIds == null) {\n            throw new FlowableIllegalArgumentException(\"Set of process definition ids is null\");\n        }\n        if (processDefinitionIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Set of process definition ids is empty\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionIds = processDefinitionIds;\n        } else {\n            this.processDefinitionIds = processDefinitionIds;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQueryImpl processDefinitionKey(String processDefinitionKey) {\n        if (processDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition key is null\");\n        }\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 ProcessInstanceQueryImpl processDefinitionKeyLike(String processDefinitionKeyLike) {\n        if (processDefinitionKeyLike == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition key is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionKeyLike = processDefinitionKeyLike;","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L419-L455","documentation":"ProcessInstanceQueryImpl.processDefinitionKey(String) throws FlowableIllegalArgumentException('Process definition key is null') when the key argument is null. The key is the business identifier of a process definition and is used as an exact-match filter; a null cannot form a valid condition, so it is rejected during query building before being stored on the query or its OR-query object.","triggerScenarios":"Calling .processDefinitionKey(null), usually when the key comes from a nullable config value, an omitted request parameter, or a variable extracted from an object whose key field is unset.","commonSituations":"Workflow launch consoles where the process key is chosen from a dropdown and no default is set; deployment scripts where the key property was renamed; API consumers omitting the key and the server passing the value straight through.","solutions":["Null-check the key before calling processDefinitionKey and skip the filter or reject the request when null","Validate/default the key at the input boundary (REST handler, config loader) before it reaches query building","Use processDefinitionId or processDefinitionName if that is what your data actually provides","Catch FlowableIllegalArgumentException and return a clear validation error to the caller"],"exampleFix":"// before\nString key = properties.getProperty(\"process.key\");\nquery.processDefinitionKey(key); // throws when property missing\n\n// after\nString key = properties.getProperty(\"process.key\");\nif (key != null) {\n    query.processDefinitionKey(key);\n} else {\n    throw new IllegalStateException(\"process.key must be configured\");\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionKey != null) {\n    query.processDefinitionKey(processDefinitionKey);\n}","typeGuard":"boolean hasDefinitionKey(String key) { return key != null && !key.isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionKey(key);\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"processDefinitionKey must not be null\", e);\n}","preventionTips":["Validate process keys at the input boundary (REST/config) before query building","Skip the key filter when the key is absent instead of passing null","Keep key names consistent between deployment and query code to avoid unset lookups","Add tests for query building with missing key configuration"],"tags":["flowable","query-validation","null-check","process-definition-key"],"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"}