{"record":{"id":"5d4495b53f70a06f","repo":"flowable/flowable-engine","slug":"process-definition-id-is-null","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/ExecutionQueryImpl.java","lineNumber":143,"sourceCode":"\n    public ExecutionQueryImpl(CommandContext commandContext, ProcessEngineConfigurationImpl processEngineConfiguration) {\n        super(commandContext, processEngineConfiguration.getVariableServiceConfiguration());\n        this.processEngineConfiguration = processEngineConfiguration;\n    }\n\n    public ExecutionQueryImpl(CommandExecutor commandExecutor, ProcessEngineConfigurationImpl processEngineConfiguration) {\n        super(commandExecutor, processEngineConfiguration.getVariableServiceConfiguration());\n        this.processEngineConfiguration = processEngineConfiguration;\n    }\n\n    public boolean isProcessInstancesOnly() {\n        return false; // see dynamic query\n    }\n\n    @Override\n    public ExecutionQueryImpl processDefinitionId(String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition id is null\");\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 ExecutionQueryImpl processDefinitionKey(String processDefinitionKey) {\n        if (processDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Process definition key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;\n        } else {\n            this.processDefinitionKey = processDefinitionKey;","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java#L125-L161","documentation":"ExecutionQuery.processDefinitionId() requires a non-null process definition id; null would remove the filter, so Flowable throws FlowableIllegalArgumentException. This applies both to normal and OR-statement query building.","triggerScenarios":"Calling executionQuery.processDefinitionId(null), typically when the id comes from a variable that was never initialized, a nullable runtime context, or a failed definition lookup.","commonSituations":"Tracing executions of a process whose id wasn't resolved from a ProcessInstance; passing a result of singleResult() that was null; missing request parameter.","solutions":["Pass a valid process definition id obtained from ProcessDefinitionQuery/RepositoryService","Only call processDefinitionId when the id is non-null; otherwise skip the filter","Null-check the result of any singleResult() lookup feeding this method"],"exampleFix":"// before\nexecutionQuery.processDefinitionId(definition.getId());\n// after\nProcessDefinition definition = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(key).latestVersion().singleResult();\nif (definition != null) {\n    executionQuery.processDefinitionId(definition.getId());\n}","handlingStrategy":"validation","validationCode":"if (processDefinitionId == null) { processDefinitionId = resolveDefinitionId(key); }\nif (processDefinitionId != null) { query.processDefinitionId(processDefinitionId); }","typeGuard":"boolean hasDefinitionId(String id) { return id != null && !id.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.processDefinitionId(id);\n} catch (FlowableIllegalArgumentException e) {\n    // query without the definition filter or report missing id\n}","preventionTips":["Null-check results of ProcessDefinitionQuery.singleResult() before use","Pass ids through a resolver that throws a domain-specific error","Validate request parameters at the controller layer"],"tags":["query","null-argument","execution"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T16:30:33.424Z"}