{"record":{"id":"0a44cd919c82ce71","repo":"flowable/flowable-engine","slug":"provided-process-definition-key-is-null","errorCode":null,"errorMessage":"Provided process definition key is null","messagePattern":"Provided process definition key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java","lineNumber":161,"sourceCode":"    }\n\n    @Override\n    public DeadLetterJobQueryImpl processDefinitionId(String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided 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 DeadLetterJobQueryImpl processDefinitionKey(String processDefinitionKey) {\n        if (processDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Provided 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 DeadLetterJobQueryImpl category(String category) {\n        if (category == null) {\n            throw new FlowableIllegalArgumentException(\"Provided category is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.category = category;\n        } else {\n            this.category = category;","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java#L143-L179","documentation":"DeadLetterJobQueryImpl.processDefinitionKey() throws FlowableIllegalArgumentException when the processDefinitionKey parameter is null. The Flowable query API validates every filter argument eagerly so that invalid queries fail at build time rather than producing broken SQL at execution time. Passing null means the caller intended to filter by process definition key but supplied no value.","triggerScenarios":"Calling deadLetterJobQuery().processDefinitionKey(null) directly, or indirectly via helper/wrapper code that forwards a possibly-null variable (e.g. processDefinitionKey from a request parameter) into the query builder.","commonSituations":"Building queries from REST request DTOs where the processDefinitionKey field is optional and not null-checked; dynamic query builders that conditionally add filters but accidentally call the setter with a null; refactors where a default key constant was removed.","solutions":["Only call processDefinitionKey(...) when the value is non-null, e.g. wrap in an if (key != null) block or Optional filter","If null should mean 'no filter', simply omit the call - the query matches all process definition keys by default","If null is invalid input, validate/reject it at the API boundary before constructing the query","Check upstream data sources (request body, config, database) for why the key is missing"],"exampleFix":"// before\nDeadLetterJobQuery query = managementService.createDeadLetterJobQuery()\n    .processDefinitionKey(request.getProcessDefinitionKey());\n\n// after\nDeadLetterJobQuery query = managementService.createDeadLetterJobQuery();\nif (request.getProcessDefinitionKey() != null) {\n    query = query.processDefinitionKey(request.getProcessDefinitionKey());\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionKey != null) {\n    query = query.processDefinitionKey(processDefinitionKey);\n}","typeGuard":"boolean hasProcessDefinitionKey(String key) { return key != null && !key.trim().isEmpty(); }","tryCatchPattern":"try {\n    return jobService.createDeadLetterJobQuery().processDefinitionKey(key).list();\n} catch (FlowableIllegalArgumentException e) {\n    throw new InvalidQueryRequestException(\"processDefinitionKey must not be null\", e);\n}","preventionTips":["Build queries conditionally: only add filters whose values are present","Use Optional.ofNullable(key).filter(k -> !k.isEmpty()) to gate the setter call","Validate query DTOs at the REST boundary with Bean Validation (@NotNull when the field is required)","Never pass values straight from external input into query setters without a null check"],"tags":["flowable","null-argument","query-builder","validation"],"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"}