{"record":{"id":"49b047f9f7c5a54f","repo":"flowable/flowable-engine","slug":"a-process-instance-id-is-required-but-the-provide-49b047","errorCode":null,"errorMessage":"A process instance id is required, but the provided id '${processInstanceId}' points to a child execution of process instance '${processInstance.getProcessInstanceId()}'.","messagePattern":"A process instance id is required, but the provided id '(.+?)' points to a child execution of process instance '(.+?)'\\.","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/UpdateProcessInstanceCmd.java","lineNumber":55,"sourceCode":"    protected ProcessInstanceUpdateBuilderImpl builder;\n\n    public UpdateProcessInstanceCmd(ProcessInstanceUpdateBuilderImpl builder) {\n        this.builder = builder;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        String processInstanceId = builder.getProcessInstanceId();\n        if (processInstanceId == null || processInstanceId.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"The process instance id is mandatory, but '\" + processInstanceId + \"' has been provided.\");\n        }\n\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\n                    + \"' points to a child execution of process instance '\" + processInstance.getProcessInstanceId() + \"'.\");\n        }\n\n        if (builder.isBusinessKeySet()) {\n            executionManager.updateProcessInstanceBusinessKey(processInstance, builder.getBusinessKey());\n        }\n\n        if (builder.isBusinessStatusSet()) {\n            executionManager.updateProcessInstanceBusinessStatus(processInstance, builder.getBusinessStatus());\n        }\n\n        if (builder.isNameSet()) {\n            processInstance.setName(builder.getName());\n            ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n            processEngineConfiguration.getHistoryManager().recordProcessInstanceNameChange(processInstance, builder.getName());\n        }\n\n        if (builder.isDueDateSet()) {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/UpdateProcessInstanceCmd.java#L37-L73","documentation":"Thrown as FlowableIllegalArgumentException when the provided id resolves to an execution row that is a child (concurrent/scope) execution rather than the process instance itself. The command requires the root process-instance execution; a child execution id cannot be used to update instance-level data like the business key or name.","triggerScenarios":"Passing an execution id obtained from ExecutionQuery / execution.getExecutionId(), a child execution inside a parallel gateway or call-activity scope, or any non-root row of ACT_RU_EXECUTION to the update-process-instance command.","commonSituations":"Confusing Execution.getId() with ProcessInstance.getId(); using the 'executionId' variable from a delegate/task context in a multi-instance or concurrent branch; iteratively updating instances whose ids came from an executions query.","solutions":["Use the process instance id: get it via execution.getProcessInstanceId() from the child execution, then call the command with that id.","In a delegate, use DelegateExecution.getProcessInstanceId() (or executionEntity.getProcessInstanceId()) instead of getId().","Re-source ids from ProcessInstanceQuery rather than ExecutionQuery when the target is instance-level data."],"exampleFix":"// before\nString id = execution.getId(); // may be a child execution\nruntimeService.setProcessInstanceName(id, name);\n// after\nString id = execution.getProcessInstanceId();\nruntimeService.setProcessInstanceName(id, name);","handlingStrategy":"validation","validationCode":"if (!processInstanceId.equals(executionQuery.executionId(executionId).singleResult().getProcessInstanceId())) { /* use getProcessInstanceId() instead */ }","typeGuard":"String toProcessInstanceId(Execution e) { return e.isProcessInstanceType() ? e.getId() : e.getProcessInstanceId(); }","tryCatchPattern":"try { runtimeService.setProcessInstanceName(id, name); } catch (FlowableIllegalArgumentException e) { LOG.error(\"id {} is a child execution\", id, e); }","preventionTips":["Never use Execution.getId() for instance-level operations; use getProcessInstanceId()","In delegates use DelegateExecution.getProcessInstanceId(), not getId()","Source instance ids from ProcessInstanceQuery, not ExecutionQuery"],"tags":["process-instance","execution","invalid-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-14T11:17:12.474Z"}