{"record":{"id":"243ecad25e447ed7","repo":"flowable/flowable-engine","slug":"process-definition-id-is-null-243eca","errorCode":null,"errorMessage":"Process definition id is null","messagePattern":"Process definition id is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":406,"sourceCode":"\n    @Override\n    public ProcessInstanceQuery processDefinitionVersion(Integer processDefinitionVersion) {\n        if (processDefinitionVersion == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition version is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionVersion = processDefinitionVersion;\n        } else {\n            this.processDefinitionVersion = processDefinitionVersion;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQueryImpl processDefinitionId(String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition id is null\");\n        }\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 ProcessInstanceQuery processDefinitionIds(Set<String> processDefinitionIds) {\n        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        }","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L388-L424","documentation":"ProcessInstanceQueryImpl.processDefinitionId(String) throws FlowableIllegalArgumentException('Process definition id is null') when the given definition id is null. The id is the primary exact-match filter for process instances, and a null cannot produce a valid equality condition, so the check rejects it during query construction before storing it on the query or its OR-query object.","triggerScenarios":"Calling .processDefinitionId(null), typically when the id comes from a variable populated by a prior lookup that returned null (e.g. singleResult() on an empty result), a missing path variable, or an unbound DTO field.","commonSituations":"Chained queries where ProcessDefinitionQuery.singleResult() returns null for a nonexistent key and its getId() result is passed on; REST handlers with optional path parameters; migrated code where an id field changed name and silently stopped being populated.","solutions":["Null-check the id before calling processDefinitionId and skip the query/filter when absent","Verify the upstream lookup actually found the definition — handle empty singleResult() before reading getId()","Use processDefinitionKey or processDefinitionName if the exact id is not known","Catch FlowableIllegalArgumentException around query building and surface a clear validation message"],"exampleFix":"// before\nProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).singleResult();\nquery.processDefinitionId(def.getId()); // NPE risk / def may be null\n\n// after\nProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).singleResult();\nif (def != null) {\n    query.processDefinitionId(def.getId());\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionId != null) {\n    query.processDefinitionId(processDefinitionId);\n}","typeGuard":"boolean hasDefinitionId(String id) { return id != null && !id.isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionId(defId);\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"processDefinitionId must not be null\", e);\n}","preventionTips":["Handle empty results from ProcessDefinitionQuery.singleResult() before reading getId()","Null-check ids extracted from DTOs or path variables before query building","Use Objects.requireNonNull with a meaningful message early in your own code","Add tests for lookups of nonexistent definitions feeding subsequent queries"],"tags":["flowable","query-validation","null-check","process-definition-id"],"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"}