{"record":{"id":"70d7340f8c0b9040","repo":"flowable/flowable-engine","slug":"process-definition-name-is-null-70d734","errorCode":null,"errorMessage":"Process definition name is null","messagePattern":"Process definition name is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":350,"sourceCode":"    \n    @Override\n    public ProcessInstanceQuery processDefinitionCategoryLikeIgnoreCase(String processDefinitionCategoryLikeIgnoreCase) {\n        if (processDefinitionCategoryLikeIgnoreCase == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition category is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionCategoryLikeIgnoreCase = processDefinitionCategoryLikeIgnoreCase;\n        } else {\n            this.processDefinitionCategoryLikeIgnoreCase = processDefinitionCategoryLikeIgnoreCase;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processDefinitionName(String processDefinitionName) {\n        if (processDefinitionName == null) {\n            throw new FlowableIllegalArgumentException(\"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 processDefinitionNameLike(String processDefinitionNameLike) {\n        if (processDefinitionNameLike == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition name is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionNameLike = processDefinitionNameLike;","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L332-L368","documentation":"ProcessInstanceQuery.processDefinitionName(String) validates its argument before storing it as a query filter. If the argument is null, the query would be semantically undefined (a null filter on the PROC_DEF_NAME_ column), so Flowable throws FlowableIllegalArgumentException early with 'Process definition name is null' instead of producing a broken SQL query. This is fail-fast input validation at query-building time, not an execution-time failure.","triggerScenarios":"Calling runtimeService.createProcessInstanceQuery().processDefinitionName(null) — either directly with a literal null or with a String variable that is null at call time.","commonSituations":"A process definition name read from configuration, a REST request parameter, or an upstream lookup is null because the definition was not found, the property is missing, or an earlier API returned null; developers also hit it when conditionally building queries and passing through unset variables without a null check.","solutions":["Check the argument with a null test before calling processDefinitionName and skip or branch the filter when it is null","Trace where the name comes from (config, request param, repository lookup) and fix the producer so it returns a real value or a sensible default","If a null filter should mean 'no filtering', omit the call entirely rather than passing null","Wrap the query building in try/catch for FlowableIllegalArgumentException to surface a clear message to the caller"],"exampleFix":"// before\nString name = repositoryService.createProcessDefinitionQuery().singleResult().getName();\nProcessInstanceQuery q = runtimeService.createProcessInstanceQuery().processDefinitionName(name); // NPE/null risk upstream, name may be null\n\n// after\nString name = repositoryService.createProcessDefinitionQuery().singleResult().getName();\nProcessInstanceQuery q = runtimeService.createProcessInstanceQuery();\nif (name != null) {\n    q = q.processDefinitionName(name);\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionName != null) {\n    query.processDefinitionName(processDefinitionName);\n}","typeGuard":"boolean hasDefinitionName(String name) { return name != null && !name.isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionName(name);\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"processDefinitionName must not be null\", e);\n}","preventionTips":["Null-check every query filter argument at the point where query building is parameterized","Build queries conditionally: only add filters whose inputs are present","Validate request/config inputs at the boundary before they reach query construction","Add unit tests covering null filter arguments"],"tags":["flowable","query-validation","null-check","process-instance-query"],"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"}