flowable/flowable-engine · error · ActivitiIllegalArgumentException

The process instance id is mandatory, but '" +…

Error message

The process instance id is mandatory, but '" + processInstanceId + "' has been provided.

What it means

SetProcessDefinitionVersionCmd's constructor validates arguments eagerly: a null or empty processInstanceId throws ActivitiIllegalArgumentException when the command object is built, before it is executed.

Solutions

  1. Pass the id from ProcessInstance.getId() (or Execution.getId()) captured at instance start.
  2. Null/empty-check the id at the call site before constructing the command.
  3. Fix the upstream lookup that returns an empty instance id.

Example fix

// before
managementService.executeCommand(new SetProcessDefinitionVersionCmd(processInstanceId, 2));
// after
if (processInstanceId != null && !processInstanceId.isEmpty()) {
    managementService.executeCommand(new SetProcessDefinitionVersionCmd(processInstanceId, 2));
}
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { managementService.executeCommand(new SetProcessDefinitionVersionCmd(piId, version)); }
catch (ActivitiIllegalArgumentException e) { log.error("invalid process instance id '{}'", piId); }

Prevention

When it happens

Trigger: new SetProcessDefinitionVersionCmd(null, version) or new SetProcessDefinitionVersionCmd("", version), e.g. via management/CommandExecutor paths that migrate a process instance to a different definition version.

Common situations: Process instance id never captured after startProcessInstanceByKey, empty request/script variables, or instance already completed so the reference was cleared.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessDefinitionVersionCmd.java:61

 * 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 http://forums.activiti.org/en/viewtopic.php?t=2918
 * @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 ActivitiIllegalArgumentException("The process instance id is mandatory, but '" + processInstanceId + "' has been provided.");
        }
        if (processDefinitionVersion == null) {
            throw new ActivitiIllegalArgumentException("The process definition version is mandatory, but 'null' has been provided.");
        }
        if (processDefinitionVersion < 1) {
            throw new ActivitiIllegalArgumentException("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 = commandContext.getExecutionEntityManager();
        ExecutionEntity processInstance = executionManager.findExecutionById(processInstanceId);
        if (processInstance == null) {

View on GitHub (pinned to d6d39ce1c6)