{"record":{"id":"07f35cde544ab5d2","repo":"Activiti/Activiti","slug":"a-process-instance-id-is-required-but-the-provide","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 ${getClass().getSimpleName()} 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":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessDefinitionVersionCmd.java","lineNumber":93,"sourceCode":"                \"' has been provided.\"\n            );\n        }\n        this.processInstanceId = processInstanceId;\n        this.processDefinitionVersion = processDefinitionVersion;\n    }\n\n    public Void execute(CommandContext commandContext) {\n        // check that the new process definition is just another version of the same\n        // process definition that the process instance is using\n        ExecutionEntityManager executionManager = commandContext.getExecutionEntityManager();\n        ExecutionEntity processInstance = executionManager.findById(processInstanceId);\n        if (processInstance == null) {\n            throw new ActivitiObjectNotFoundException(\n                \"No process instance found for id = '\" + processInstanceId + \"'.\",\n                ProcessInstance.class\n            );\n        } else if (!processInstance.isProcessInstanceType()) {\n            throw new ActivitiIllegalArgumentException(\n                \"A process instance id is required, but the provided id \" +\n                \"'\" +\n                processInstanceId +\n                \"' \" +\n                \"points to a child execution of process instance \" +\n                \"'\" +\n                processInstance.getProcessInstanceId() +\n                \"'. \" +\n                \"Please invoke the \" +\n                getClass().getSimpleName() +\n                \" with a root execution id.\"\n            );\n        }\n\n        DeploymentManager deploymentCache = commandContext.getProcessEngineConfiguration().getDeploymentManager();\n        ProcessDefinition currentProcessDefinition = deploymentCache.findDeployedProcessDefinitionById(\n            processInstance.getProcessDefinitionId()\n        );","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/Activiti/Activiti/blob/56435b1a97deeafdc09dd40074b056c89fba5a8a/activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessDefinitionVersionCmd.java#L75-L111","documentation":"The provided id exists but points to a child execution (a concurrent branch or scope) rather than the root process instance execution — ExecutionEntity.isProcessInstanceType() returned false. Activiti requires a root execution id for version switching, so it throws ActivitiIllegalArgumentException and tells you the parent process instance id to use instead.","triggerScenarios":"Passing an Execution.getId() (from runtimeService.createExecutionQuery() or a receive-task/message correlation) into setProcessDefinitionVersion instead of the ProcessInstance.getId().","commonSituations":"Code that holds only an ExecutionEntity (e.g. inside a delegate or event listener) and uses its id directly; message boundary events on embedded sub-processes returning child execution ids.","solutions":["Resolve the root id: execution.getProcessInstanceId() gives the process instance id — use that","If you have an ExecutionEntity, check isProcessInstanceType() before using its id","Get ids from runtimeService.createProcessInstanceQuery() instead of createExecutionQuery() when you need instances"],"exampleFix":"// before\nruntimeService.setProcessDefinitionVersion(execution.getId(), version); // child execution\n// after\nruntimeService.setProcessDefinitionVersion(execution.getProcessInstanceId(), version);","handlingStrategy":"type-guard","validationCode":"if (executionEntity != null && !executionEntity.isProcessInstanceType()) {\n    instanceId = executionEntity.getProcessInstanceId();\n}","typeGuard":"String toProcessInstanceId(ExecutionEntity e) {\n    return (e != null && e.isProcessInstanceType()) ? e.getId() : e.getProcessInstanceId();\n}","tryCatchPattern":"try {\n    runtimeService.setProcessDefinitionVersion(executionId, version);\n} catch (ActivitiIllegalArgumentException e) {\n    log.error(\"Need root execution id: {}\", e.getMessage());\n}","preventionTips":["Distinguish Execution.getId() from ProcessInstance.getId() in your domain model","In delegates, always use getProcessInstanceId() for instance-level operations","Never feed execution-query results into instance-level APIs unchecked"],"tags":["activiti","wrong-argument","execution-tree","process-instance-migration"],"backgroundTag":"invalid-argument-value","analyzedSha":"56435b1a97deeafdc09dd40074b056c89fba5a8a","analyzedAt":"2026-09-09T21:00:06.703Z","contentChangedAt":"2026-09-09T21:00:06.703Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}