{"record":{"id":"a139e0e82849ee33","repo":"flowable/flowable-engine","slug":"a-process-instance-id-is-required-but-the-provide-a139e0","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/SetProcessDefinitionVersionCmd.java","lineNumber":86,"sourceCode":"            throw new FlowableIllegalArgumentException(\"The process definition version is mandatory, but 'null' has been provided.\");\n        }\n        if (processDefinitionVersion < 1) {\n            throw new FlowableIllegalArgumentException(\"The process definition version must be positive, but '\" + processDefinitionVersion + \"' has been provided.\");\n        }\n        this.processInstanceId = processInstanceId;\n        this.processDefinitionVersion = processDefinitionVersion;\n    }\n\n    @Override\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 = 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        } 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        DeploymentManager deploymentCache = CommandContextUtil.getProcessEngineConfiguration(commandContext).getDeploymentManager();\n        ProcessDefinition currentProcessDefinition = deploymentCache.findDeployedProcessDefinitionById(processInstance.getProcessDefinitionId());\n\n        ProcessDefinition newProcessDefinition = deploymentCache\n                .findDeployedProcessDefinitionByKeyAndVersionAndTenantId(currentProcessDefinition.getKey(), processDefinitionVersion, currentProcessDefinition.getTenantId());\n\n        if (Flowable5Util.isFlowable5ProcessDefinition(currentProcessDefinition, commandContext) && !Flowable5Util\n            .isFlowable5ProcessDefinition(newProcessDefinition, commandContext)) {\n            throw new FlowableIllegalArgumentException(\"The current process definition (id = '\" + currentProcessDefinition.getId() + \"') is a v5 definition.\"\n                + \" However the new process definition (id = '\" + newProcessDefinition.getId() + \"') is not a v5 definition.\");\n        }\n\n        validateAndSwitchVersionOfExecution(commandContext, processInstance, newProcessDefinition);\n\n        // switch the historic process instance to the new process definition version","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessDefinitionVersionCmd.java#L68-L104","documentation":"execute() requires the id to reference the root process instance execution. If findById returns a child execution (e.g. a scope or concurrent execution), isProcessInstanceType() is false and it throws FlowableIllegalArgumentException directing the caller to use a root execution id.","triggerScenarios":"Passing the id of a child/concurrent execution or execution-scoped id (e.g. from an Execution listener or execution query) into SetProcessDefinitionVersionCmd instead of the process instance's root id.","commonSituations":"Iterating RuntimeService.createExecutionQuery() results and treating every execution id as a process instance id; using execution.getId() from an activity context where getProcessInstanceId() was the correct value.","solutions":["Use execution.getProcessInstanceId() to obtain the root id before invoking the command","Query process instances with RuntimeService.createProcessInstanceQuery() rather than execution queries","Verify the id is of type ProcessInstance before calling the command"],"exampleFix":"// before\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(execution.getId(), 2));\n// after\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(execution.getProcessInstanceId(), 2));","handlingStrategy":"type-guard","validationCode":"ExecutionEntity e = executionEntityManager.findById(id);\nboolean isRoot = e != null && e.isProcessInstanceType();","typeGuard":"boolean isProcessInstance(Execution e) { return e instanceof ProcessInstance; }","tryCatchPattern":"try { cmd.execute(ctx); } catch (FlowableIllegalArgumentException e) { /* retry with getProcessInstanceId() root id */ }","preventionTips":["Always use getProcessInstanceId(), never execution id, for this command","Use ProcessInstanceQuery instead of ExecutionQuery to obtain ids","Document that child executions are invalid inputs"],"tags":["process-instance","execution","argument"],"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-14T16:17:12.679Z"}