{"record":{"id":"65beb08c732f7666","repo":"flowable/flowable-engine","slug":"root-process-instance-id-is-null","errorCode":null,"errorMessage":"Root process instance id is null","messagePattern":"Root process instance 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":329,"sourceCode":"        if (processInstanceIds == null) {\n            throw new FlowableIllegalArgumentException(\"Set of process instance ids is null\");\n        }\n        if (processInstanceIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Set of process instance ids is empty\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processInstanceIds = processInstanceIds;\n        } else {\n            this.processInstanceIds = processInstanceIds;\n        }\n        return this;\n    }\n\n    @Override\n    public ExecutionQueryImpl rootProcessInstanceId(String rootProcessInstanceId) {\n        if (rootProcessInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Root process instance id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.rootProcessInstanceId = rootProcessInstanceId;\n        } else {\n            this.rootProcessInstanceId = rootProcessInstanceId;\n        }\n        return this;\n    }\n\n    @Override\n    public ExecutionQuery processInstanceBusinessKey(String businessKey) {\n        if (businessKey == null) {\n            throw new FlowableIllegalArgumentException(\"Business key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.businessKey = businessKey;\n        } else {\n            this.businessKey = businessKey;","sourceCodeStart":311,"sourceCodeEnd":347,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java#L311-L347","documentation":"ExecutionQueryImpl.rootProcessInstanceId(String) throws FlowableIllegalArgumentException when the root process instance id is null. The root-id filter must be a concrete value to constrain the query to a process-instance tree. Fail-fast validation happens at query construction.","triggerScenarios":"Calling rootProcessInstanceId(null), typically when the root id comes from a parent-context lookup or an optional variable that was null.","commonSituations":"Child-process handling code where the root instance was already ended; copying query parameters from another execution whose root id was never set; misread variable in a delegate.","solutions":["Null-check the root id before constructing the query","Resolve the root instance id from the execution (historyService/runtimeService) and handle the not-found case","If the tree root is unknown, drop this filter or use processInstanceId instead","Catch FlowableIllegalArgumentException if null input is an accepted condition"],"exampleFix":"// before\nExecutionQuery query = runtimeService.createExecutionQuery().rootProcessInstanceId(rootId);\n// after\nExecutionQuery query = runtimeService.createExecutionQuery();\nif (rootId != null) {\n    query.rootProcessInstanceId(rootId);\n}","handlingStrategy":"validation","validationCode":"if (rootId == null) {\n    throw new IllegalArgumentException(\"rootProcessInstanceId must not be null\");\n}","typeGuard":"boolean hasRootId(String rootId) {\n    return rootId != null && !rootId.isBlank();\n}","tryCatchPattern":"try {\n    ExecutionQuery q = runtimeService.createExecutionQuery().rootProcessInstanceId(rootId);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Missing root process instance id: {}\", e.getMessage());\n}","preventionTips":["Resolve the root id from the current execution before querying by it","Make root-id filters conditional when the root may be unknown","Use Objects.requireNonNull at the method boundary for fail-fast clarity"],"tags":["flowable","null-check","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"}