flowable/flowable-engine · error · FlowableIllegalArgumentException

The process instance id is mandatory, but '${processInstance

Error message

The process instance id is mandatory, but '${processInstanceId}' has been provided.

What it means

SetProcessDefinitionVersionCmd's constructor validates that processInstanceId is non-null and non-empty, throwing FlowableIllegalArgumentException otherwise. This is eager constructor-time argument validation: the command instance cannot even be created without a valid process instance id. The message interpolates the offending value (typically the string 'null' or '').

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessDefinitionVersionCmd.java:65

 * The command will fail, if there is already a {@link ProcessInstance} or {@link HistoricProcessInstance} using the new process definition version and the same business key as the
 * {@link ProcessInstance} that is to be migrated.
 * 
 * If the process instance is not currently waiting but actively running, then this would be a case for optimistic locking, meaning either the version update or the "real work" wins, i.e., this is a
 * race condition.
 * 
 * @see <a href="http://forums.activiti.org/en/viewtopic.php?t=2918">http://forums.activiti.org/en/viewtopic.php?t=2918</a>
 * @author Falko Menge
 */
public class SetProcessDefinitionVersionCmd implements Command<Void>, Serializable {

    private static final long serialVersionUID = 1L;

    private final String processInstanceId;
    private final Integer processDefinitionVersion;

    public SetProcessDefinitionVersionCmd(String processInstanceId, Integer processDefinitionVersion) {
        if (processInstanceId == null || processInstanceId.length() < 1) {
            throw new FlowableIllegalArgumentException("The process instance id is mandatory, but '" + processInstanceId + "' has been provided.");
        }
        if (processDefinitionVersion == null) {
            throw new FlowableIllegalArgumentException("The process definition version is mandatory, but 'null' has been provided.");
        }
        if (processDefinitionVersion < 1) {
            throw new FlowableIllegalArgumentException("The process definition version must be positive, but '" + processDefinitionVersion + "' has been provided.");
        }
        this.processInstanceId = processInstanceId;
        this.processDefinitionVersion = processDefinitionVersion;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        // check that the new process definition is just another version of the same
        // process definition that the process instance is using
        ExecutionEntityManager executionManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExecutionEntity processInstance = executionManager.findById(processInstanceId);
        if (processInstance == null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the process instance exists via RuntimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() before constructing the command
2. Reject null/empty ids at your own call site before invoking the command
3. If the id comes from a query result, null-check it first

Example fix

// before
managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, 2));
// after
if (instanceId == null || instanceId.isEmpty()) {
    throw new IllegalStateException("processInstanceId is required");
}
managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, 2));

if (processInstanceId == null || processInstanceId.isEmpty()) {
    throw new IllegalArgumentException("processInstanceId required");
}

boolean isValidProcessInstanceId(String id) {
    return id != null && !id.trim().isEmpty();
}

try {
    managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));
} catch (FlowableIllegalArgumentException e) {
    log.error("Invalid arguments for SetProcessDefinitionVersionCmd", e);
}

When it happens

Trigger: Constructing new SetProcessDefinitionVersionCmd(null, version) or new SetProcessDefinitionVersionCmd("", version), often when the instance id comes from a null return of a runtime service query or an unset variable.

Common situations: execution.getProcessInstanceId() returning null in early lifecycle callbacks; empty-string ids produced by broken deserialization; copy-paste passing the wrong variable into the constructor.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• text is null
• The command is null
• The config is null
• version is null
• ProcessInstanceId cannot be null.

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