{"record":{"id":"e26c3b2a2cfaa695","repo":"flowable/flowable-engine","slug":"a-process-instance-id-is-required-but-the-provide-e26c3b","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/SetProcessInstanceBusinessKeyCmd.java","lineNumber":66,"sourceCode":"\n        this.processInstanceId = processInstanceId;\n        this.businessKey = businessKey;\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            if (CommandContextUtil.getProcessEngineConfiguration(commandContext).isFlowable5CompatibilityEnabled()) {\n                CommandContextUtil.getProcessEngineConfiguration(commandContext).getFlowable5CompatibilityHandler().updateBusinessKey(processInstanceId,\n                        businessKey);\n                return null;\n            }\n            \n            throw new FlowableObjectNotFoundException(\"No process instance found for id = '\" + processInstanceId + \"'.\", ProcessInstance.class);\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        if (Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, processInstance.getProcessDefinitionId())) {\n            CommandContextUtil.getProcessEngineConfiguration(commandContext).getFlowable5CompatibilityHandler().updateBusinessKey(processInstanceId, businessKey);\n            return null;\n        }\n\n        executionManager.updateProcessInstanceBusinessKey(processInstance, businessKey);\n\n        return null;\n    }\n}\n","sourceCodeStart":48,"sourceCodeEnd":80,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceBusinessKeyCmd.java#L48-L80","documentation":"Thrown by execute() when the given id resolves to an execution, but that execution is a child execution rather than the root process-instance execution. Business key is stored on the root execution, so Flowable refuses to set it on a child and points you at the correct root id.","triggerScenarios":"Calling RuntimeService.setProcessInstanceBusinessKey with an execution id obtained from a task's getExecutionId() (which is usually a child/scope execution), not from ProcessInstance.getId().","commonSituations":"Developers inside a delegate/task listener use DelegateExecution.getId() or Task.getExecutionId() and pass that as a process instance id; scope executions (embedded sub-processes, call activities) frequently differ from the root id.","solutions":["Use processInstance.getId() / execution.getProcessInstanceId() (root id) instead of the child execution id.","If you only have an Execution, call execution.getProcessInstanceId() to get the root and pass that.","Query RuntimeService.createProcessInstanceQuery().processInstanceId(...) to confirm the id is of process instance type."],"exampleFix":"// before\nruntimeService.setProcessInstanceBusinessKey(task.getExecutionId(), key);\n// after\nruntimeService.setProcessInstanceBusinessKey(task.getProcessInstanceId(), key);","handlingStrategy":"type-guard","validationCode":"ProcessInstance pi = runtimeService.createProcessInstanceQuery()\n        .processInstanceId(candidateId).singleResult();\nboolean isRoot = pi != null && candidateId.equals(pi.getId());","typeGuard":"boolean isProcessInstanceRoot(String id, RuntimeService rs) {\n    ProcessInstance pi = rs.createProcessInstanceQuery().processInstanceId(id).singleResult();\n    return pi != null && pi.getProcessInstanceId() == null || (pi != null && id.equals(pi.getId()));\n}","tryCatchPattern":"try {\n    runtimeService.setProcessInstanceBusinessKey(id, key);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"points to a child execution\")) {\n        // switch to execution.getProcessInstanceId() and retry\n    }\n}","preventionTips":["Always use ProcessInstance.getId()/getProcessInstanceId(), never Task/child execution ids.","In delegates, use DelegateExecution.getProcessInstanceId().","Remember sub-processes and call activities create child executions with different ids."],"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"}