{"record":{"id":"20d78de8776b43f0","repo":"flowable/flowable-engine","slug":"process-definition-name-is-null-20d78d","errorCode":null,"errorMessage":"Process definition name is null","messagePattern":"Process definition name is null","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":206,"sourceCode":"\n    @Override\n    public ProcessInstanceQuery processDefinitionCategory(String processDefinitionCategory) {\n        if (processDefinitionCategory == null) {\n            throw new ActivitiIllegalArgumentException(\"Process definition category is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionCategory = processDefinitionCategory;\n        } else {\n            this.processDefinitionCategory = processDefinitionCategory;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processDefinitionName(String processDefinitionName) {\n        if (processDefinitionName == null) {\n            throw new ActivitiIllegalArgumentException(\"Process definition name is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionName = processDefinitionName;\n        } else {\n            this.processDefinitionName = processDefinitionName;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processDefinitionVersion(Integer processDefinitionVersion) {\n        if (processDefinitionVersion == null) {\n            throw new ActivitiIllegalArgumentException(\"Process definition version is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionVersion = processDefinitionVersion;","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java#L188-L224","documentation":"ProcessInstanceQueryImpl.processDefinitionName(String) throws ActivitiIllegalArgumentException when the processDefinitionName argument is null. The query API treats null as an invalid filter value and rejects it eagerly so the failure surfaces at query construction rather than during SQL execution. To leave the filter unset, simply do not call the method.","triggerScenarios":"Calling .processDefinitionName(null) — typically the name comes from an unvalidated request parameter, a UI filter that was left blank, or a lookup that returned null.","commonSituations":"Search screens that forward all filter fields regardless of whether the user filled them; deserialized filter DTOs with null fields applied blindly; renaming a form field so the old lookup returns null.","solutions":["Apply the filter conditionally: only call processDefinitionName when the value is non-null.","Coalesce blank/absent input to 'no filter' rather than null.","Validate incoming DTOs (e.g. @NotNull or manual checks) before mapping them into query calls.","Catch ActivitiIllegalArgumentException and convert it into a client-facing validation message."],"exampleFix":"// before\nquery.processDefinitionName(filter.getName());\n// after\nif (filter.getName() != null) {\n    query = query.processDefinitionName(filter.getName());\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionName != null) {\n    query = query.processDefinitionName(processDefinitionName);\n}","typeGuard":"boolean hasDefinitionName(String name) { return name != null && !name.isEmpty(); }","tryCatchPattern":"try {\n    result = query.processDefinitionName(name).list();\n} catch (ActivitiIllegalArgumentException e) {\n    if (e.getMessage().contains(\"Process definition name is null\")) {\n        throw new BadRequestException(\"processDefinitionName must not be null\");\n    }\n    throw e;\n}","preventionTips":["Only call filter setters for values the user actually provided.","Use @NotBlank validation on REST DTO fields feeding queries.","Normalize UI empty strings to null and then skip the filter.","Add a unit test covering null-filter-path of your query builder."],"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-14T05:17:10.506Z"}