{"record":{"id":"df71144f0d43c069","repo":"flowable/flowable-engine","slug":"a-process-instance-id-is-required-but-the-provide-df7114","errorCode":null,"errorMessage":"A process instance id is required, but the provided id '${processInstanceId}' points to a child execution of process instance '${processInstance.getProcessInstanceId()}'. Please invoke the ${class simple name} with a root execution id.","messagePattern":"A process instance id is required, but the provided id '(.+?)' points to a child execution of process instance '(.+?)'\\. Please invoke the (.+?) with a root execution id\\.","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceBusinessStatusCmd.java","lineNumber":60,"sourceCode":"            throw new FlowableIllegalArgumentException(\"The process instance id is mandatory, but '\" + processInstanceId + \"' has been provided.\");\n        }\n        if (businessStatus == null) {\n            throw new FlowableIllegalArgumentException(\"The business status is mandatory, but 'null' has been provided.\");\n        }\n\n        this.processInstanceId = processInstanceId;\n        this.businessStatus = businessStatus;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        ExecutionEntityManager executionManager = CommandContextUtil.getExecutionEntityManager(commandContext);\n        ExecutionEntity processInstance = executionManager.findById(processInstanceId);\n        if (processInstance == null) {\n            throw new FlowableObjectNotFoundException(\"No process instance found for id = '\" + processInstanceId + \"'.\", ProcessInstance.class);\n\n        } else if (!processInstance.isProcessInstanceType()) {\n            throw new FlowableIllegalArgumentException(\"A process instance id is required, but the provided id \" + \"'\" + processInstanceId + \"' \" + \"points to a child execution of process instance \" + \"'\"\n                    + processInstance.getProcessInstanceId() + \"'. \" + \"Please invoke the \" + getClass().getSimpleName() + \" with a root execution id.\");\n        }\n\n        executionManager.updateProcessInstanceBusinessStatus(processInstance, businessStatus);\n\n        return null;\n    }\n}\n","sourceCodeStart":42,"sourceCodeEnd":69,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceBusinessStatusCmd.java#L42-L69","documentation":"Thrown when the supplied id belongs to a child execution rather than the root process instance execution. Business status lives on the root execution, so the command rejects child execution ids and suggests using the root id.","triggerScenarios":"Passing Task.getExecutionId() or DelegateExecution.getId() (a child scope execution) to setProcessInstanceBusinessStatus instead of the process instance id.","commonSituations":"Code inside task listeners or JavaDelegates that has an Execution/Task at hand and mistakes the execution id for the process instance id, common with embedded sub-processes and call activities.","solutions":["Use execution.getProcessInstanceId() (or task.getProcessInstanceId()) as the id argument.","Confirm via RuntimeService.createProcessInstanceQuery() that the id is a process instance.","Refactor delegates to always resolve the root id before calling the API."],"exampleFix":"// before\nruntimeService.setProcessInstanceBusinessStatus(execution.getId(), status);\n// after\nruntimeService.setProcessInstanceBusinessStatus(execution.getProcessInstanceId(), status);","handlingStrategy":"validation","validationCode":"ProcessInstance pi = runtimeService.createProcessInstanceQuery()\n        .processInstanceId(candidateId).singleResult();\nif (pi == null || !candidateId.equals(pi.getId())) {\n    throw new IllegalArgumentException(\"must pass a root process instance id\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.setProcessInstanceBusinessStatus(id, status);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"child execution\")) {\n        String rootId = execution.getProcessInstanceId();\n        runtimeService.setProcessInstanceBusinessStatus(rootId, status);\n    }\n}","preventionTips":["Prefer execution.getProcessInstanceId() over execution.getId() in delegates/listeners.","Remember scope executions of sub-processes are not process instances.","Keep helper methods that resolve the root id once and reuse it."],"tags":["process-instance","wrong-identifier","validation"],"backgroundTag":"invalid-argument-value","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"}