{"record":{"id":"bdb6de6cb59da498","repo":"flowable/flowable-engine","slug":"process-definition-key-is-null-bdb6de","errorCode":null,"errorMessage":"Process definition key is null","messagePattern":"Process definition key is null","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":265,"sourceCode":"        if (processDefinitionIds == null) {\n            throw new ActivitiIllegalArgumentException(\"Set of process definition ids is null\");\n        }\n        if (processDefinitionIds.isEmpty()) {\n            throw new ActivitiIllegalArgumentException(\"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 ActivitiIllegalArgumentException(\"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 ProcessInstanceQuery processDefinitionKeys(Set<String> processDefinitionKeys) {\n        if (processDefinitionKeys == null) {\n            throw new ActivitiIllegalArgumentException(\"Set of process definition keys is null\");\n        }\n        if (processDefinitionKeys.isEmpty()) {\n            throw new ActivitiIllegalArgumentException(\"Set of process definition keys is empty\");\n        }","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java#L247-L283","documentation":"ProcessInstanceQueryImpl.processDefinitionKey(String) throws ActivitiIllegalArgumentException when the processDefinitionKey argument is null. The key (the BPMN process id) must be a concrete non-null value; null is treated as an invalid filter and rejected at query build time. To filter by a prefix use processDefinitionKeyLike, or omit the call for no filtering.","triggerScenarios":"Calling .processDefinitionKey(null) — usually a key read from a request parameter, BPMN config, or lookup map that is missing/null.","commonSituations":"REST controllers passing unvalidated path/query params; process key resolved from an external config that changed names; Optional.map chains returning null when the source was empty.","solutions":["Null-check the key before calling; skip the filter or fail with your own message if absent.","Prefer conditional query building so unset filters are simply not applied.","Validate request parameters with @NotNull/@NotBlank or manual checks before query construction.","Catch ActivitiIllegalArgumentException around query building and surface a named-parameter validation error."],"exampleFix":"// before\nProcessInstanceQuery q = runtimeService.createProcessInstanceQuery()\n    .processDefinitionKey(param);\n// after\nProcessInstanceQuery q = runtimeService.createProcessInstanceQuery();\nif (param != null) {\n    q = q.processDefinitionKey(param);\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionKey != null) {\n    query = query.processDefinitionKey(processDefinitionKey);\n}","typeGuard":"boolean hasDefinitionKey(String key) { return key != null && !key.trim().isEmpty(); }","tryCatchPattern":"try {\n    result = query.processDefinitionKey(key).list();\n} catch (ActivitiIllegalArgumentException e) {\n    if (e.getMessage().contains(\"Process definition key is null\")) {\n        throw new BadRequestException(\"processDefinitionKey must not be null\");\n    }\n    throw e;\n}","preventionTips":["Validate request/path parameters with @NotNull/@NotBlank before query building.","Skip filter setters for absent values via conditional chaining.","Keep a single query-builder helper enforcing null-guards for all filters.","Verify external config keys exist at startup to avoid null keys at runtime."],"tags":["java","activiti","flowable","null-argument","query-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"}