flowable/flowable-engine · error · FlowableIllegalArgumentException

A process instance id is required, but the provided id '${pr

Error message

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.

What it means

SetProcessInstanceDueDateCmd requires the id of a root process instance execution. Flowable internally splits a process instance into a tree of executions; the given id resolved to a child execution instead of the root, so the command refuses to set a due date on it. This guards against callers passing execution ids from history/jobs instead of the actual process instance id.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceDueDateCmd.java:58

    public SetProcessInstanceDueDateCmd(String processInstanceId, Date dueDate) {
        if (processInstanceId == null || processInstanceId.isEmpty()) {
            throw new FlowableIllegalArgumentException("The process instance id is mandatory, but '" + processInstanceId + "' has been provided.");
        }

        this.processInstanceId = processInstanceId;
        this.dueDate = dueDate;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        ExecutionEntityManager executionManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExecutionEntity processInstance = executionManager.findById(processInstanceId);
        if (processInstance == null) {
            throw new FlowableObjectNotFoundException("No process instance found for id = '" + processInstanceId + "'.", ProcessInstance.class);

        } else if (!processInstance.isProcessInstanceType()) {
            throw new FlowableIllegalArgumentException("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.");
        }

        executionManager.updateProcessInstanceDueDate(processInstance, dueDate);

        return null;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Use processInstance.getId() (or execution.getProcessInstanceId() from any child execution) to get the root id and pass that to setProcessInstanceDueDate.
2. Verify the id at the source: if you only have an execution, call execution.getProcessInstanceId() before invoking the command.
3. Check whether you fetched the execution from a child-execution query (e.g. by activity) instead of the process instance itself.

Example fix

// before
runtimeService.setProcessInstanceDueDate(execution.getId(), dueDate);
// after
runtimeService.setProcessInstanceDueDate(execution.getProcessInstanceId(), dueDate);

ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult();
if (pi == null) throw new IllegalArgumentException("not a process instance id: " + id);
runtimeService.setProcessInstanceDueDate(pi.getId(), dueDate);

try {
    runtimeService.setProcessInstanceDueDate(id, dueDate);
} catch (FlowableIllegalArgumentException e) {
    log.warn("id {} is a child execution", id, e);
}

When it happens

Trigger: Calling runtimeService.setProcessInstanceDueDate(processInstanceId, dueDate) with an id that belongs to a concurrent/child execution rather than the root execution of the instance.

Common situations: Passing ExecutionEntity.getId() from a listener or job handler where child executions exist; confusing execution ids and process instance ids in custom code; fetching ids from history tables that record child executions.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot find process instance with id
• Cannot find process instance with id ${processInstanceId}
• A process instance id is required, but the provided id '" +
• process instance ${processInstanceId} doesn't exist, the giv
• A process instance id is required, but the provided id '${pr

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/61acadbb42ea40ed. Report an issue: GitHub.