{"record":{"id":"4665bb97365af988","repo":"flowable/flowable-engine","slug":"process-definition-id-is-null-4665bb","errorCode":null,"errorMessage":"Process definition id is null","messagePattern":"Process definition id is null","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":234,"sourceCode":"\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;\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 ActivitiIllegalArgumentException(\"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 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        }","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java#L216-L252","documentation":"ProcessInstanceQueryImpl.processDefinitionId(String) throws ActivitiIllegalArgumentException when the processDefinitionId argument is null. The query API validates filter arguments eagerly, and null is not a valid definition id. Note a non-null but malformed id will instead surface later as an empty result or entity-not-found, so this specific error purely indicates a null argument.","triggerScenarios":"Calling .processDefinitionId(null) — usually when the id comes from a path/lookup (repositoryService call, request path variable) that resolved to null, or a variable holding the definition was never initialized.","commonSituations":"Optional lookups (e.g. by key+version) returning null and the result fed straight into the query; null path variables in controllers; beans wired before properties were populated.","solutions":["Verify the definition id source is non-null before building the query; fail earlier with a clear message.","If the id is unknown, decide explicitly: either resolve it via the repository service or use a different filter (key, key-like).","Null-check lookup results from RepositoryService before chaining them into the query.","Catch ActivitiIllegalArgumentException and report which required parameter was missing."],"exampleFix":"// before\nString defId = findDefinitionId(key, version); // may return null\nruntimeService.createProcessInstanceQuery().processDefinitionId(defId);\n// after\nString defId = findDefinitionId(key, version);\nif (defId == null) throw new IllegalStateException(\"no definition for \" + key);\nruntimeService.createProcessInstanceQuery().processDefinitionId(defId);","handlingStrategy":"validation","validationCode":"if (processDefinitionId == null) {\n    throw new IllegalStateException(\"process definition id is required\");\n}\nquery = query.processDefinitionId(processDefinitionId);","typeGuard":"boolean hasDefinitionId(String id) { return id != null && !id.trim().isEmpty(); }","tryCatchPattern":"try {\n    result = query.processDefinitionId(defId).list();\n} catch (ActivitiIllegalArgumentException e) {\n    if (e.getMessage().contains(\"Process definition id is null\")) {\n        throw new BadRequestException(\"processDefinitionId must not be null\");\n    }\n    throw e;\n}","preventionTips":["Null-check results of definition lookups before chaining them into queries.","Fail fast when a required id cannot be resolved rather than querying with null.","Use Optional for lookup results and orElseThrow to make the requirement explicit.","Cover lookup-miss paths in tests so null ids never reach query construction."],"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-14T11:17:12.474Z"}