{"record":{"id":"c848439e6306e024","repo":"flowable/flowable-engine","slug":"a-process-instance-id-is-required-but-the-provide-c84843","errorCode":null,"errorMessage":"A process instance id is required, but the provided id '<processInstanceId>' points to a child execution of process instance '<processInstanceId>'. Please invoke the SetProcessInstanceBusinessKeyCmd with a root execution id.","messagePattern":"A process instance id is required, but the provided id '<processInstanceId>' points to a child execution of process instance '<processInstanceId>'\\. Please invoke the SetProcessInstanceBusinessKeyCmd with a root execution id\\.","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessInstanceBusinessKeyCmd.java","lineNumber":57,"sourceCode":"        if (processInstanceId == null || processInstanceId.length() < 1) {\n            throw new ActivitiIllegalArgumentException(\"The process instance id is mandatory, but '\" + processInstanceId + \"' has been provided.\");\n        }\n        if (businessKey == null) {\n            throw new ActivitiIllegalArgumentException(\"The business key is mandatory, but 'null' has been provided.\");\n        }\n\n        this.processInstanceId = processInstanceId;\n        this.businessKey = businessKey;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        ExecutionEntityManager executionManager = commandContext.getExecutionEntityManager();\n        ExecutionEntity processInstance = executionManager.findExecutionById(processInstanceId);\n        if (processInstance == null) {\n            throw new ActivitiObjectNotFoundException(\"No process instance found for id = '\" + processInstanceId + \"'.\", ProcessInstance.class);\n        } else if (!processInstance.isProcessInstanceType()) {\n            throw new ActivitiIllegalArgumentException(\n                    \"A process instance id is required, but the provided id \" +\n                            \"'\" + processInstanceId + \"' \" +\n                            \"points to a child execution of process instance \" +\n                            \"'\" + processInstance.getProcessInstanceId() + \"'. \" +\n                            \"Please invoke the \" + getClass().getSimpleName() + \" with a root execution id.\");\n        }\n\n        processInstance.updateProcessBusinessKey(businessKey);\n\n        return null;\n    }\n}\n","sourceCodeStart":39,"sourceCodeEnd":70,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessInstanceBusinessKeyCmd.java#L39-L70","documentation":"As with the version-migration command, findExecutionById may return a non-root execution. When !processInstance.isProcessInstanceType() the command throws ActivitiIllegalArgumentException instructing the caller to invoke SetProcessInstanceBusinessKeyCmd with a root execution id, since the business key belongs to the process instance, not to a child execution.","triggerScenarios":"Passing an executionId from an ExecutionQuery, DelegateExecution.getExecutionId() in a concurrent branch, or TaskEntity.getExecutionId() into runtimeService.setBusinessKey.","commonSituations":"Parallel gateways / multi-instance activities producing multiple executions; listeners capturing execution ids and reusing them as instance ids later.","solutions":["Use the root id: execution.getProcessInstanceId() instead of execution.getId().","Look up the instance via createProcessInstanceQuery() rather than createExecutionQuery().","Store processInstanceId (not executionId) wherever the business key will be updated later."],"exampleFix":"// before\nruntimeService.setBusinessKey(task.getExecutionId(), key); // may be a child execution\n// after\nruntimeService.setBusinessKey(task.getProcessInstanceId(), key);","handlingStrategy":"validation","validationCode":"String rootId = execution.isProcessInstanceType() ? execution.getId() : execution.getProcessInstanceId();\nruntimeService.setBusinessKey(rootId, key);","typeGuard":"boolean isRootExecution(Execution e) { return e.isProcessInstanceType(); }","tryCatchPattern":"try {\n    runtimeService.setBusinessKey(pid, key);\n} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {\n    // resolve root processInstanceId and retry\n}","preventionTips":["Persist processInstanceId (not executionId) as your correlation reference","Be aware parallel/multi-instance branches create child executions with distinct ids"],"tags":["java","flowable","argument-validation","execution-id"],"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"}