flowable/flowable-engine · error · ActivitiIllegalArgumentException

The process definition version is mandatory, but 'null' has…

Error message

The process definition version is mandatory, but 'null' has been provided.

What it means

SetProcessDefinitionVersionCmd is a command that migrates a running process instance to a different version of the same process definition. Flowable5 validates all constructor arguments eagerly; a null processDefinitionVersion makes the migration target meaningless, so the command throws ActivitiIllegalArgumentException before any work is done.

Solutions

Pass an explicit positive Integer version, e.g. new SetProcessDefinitionVersionCmd(pid, 2).
Resolve the current definition first: processEngine.getRepositoryService().createProcessDefinitionQuery().processDefinitionKey(key).orderByProcessDefinitionVersion().desc().singleResult() and pass its getVersion().
Guard the value in caller code before constructing the command and fail with a clearer domain-specific message.

Example fix

// before
runtimeService.setProcessDefinitionVersion(processInstanceId, versionFromConfig); // versionFromConfig is null
// after
if (versionFromConfig == null) {
    throw new IllegalArgumentException("No version configured for migration of " + processInstanceId);
}
runtimeService.setProcessDefinitionVersion(processInstanceId, versionFromConfig);

Defensive patterns

Strategy: validation

Validate before calling

if (processDefinitionVersion == null || processDefinitionVersion < 1) {
    throw new IllegalArgumentException("processDefinitionVersion must be a positive integer");
}

Type guard

boolean isValidVersion(Integer v) { return v != null && v >= 1; }

Try / catch

try {
    runtimeService.setProcessDefinitionVersion(pid, version);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // log and reject the migration request
}

Prevention

Always resolve the version from ProcessDefinitionQuery rather than passing user/config input directly
Validate constructor inputs at the service boundary
Use Integer (nullable) deliberately and check null before engine calls

When it happens

Trigger: Calling new SetProcessInstanceVersionCmd(processInstanceId, null) — typically when the caller read the version from a nullable variable or an API response that did not carry the version field.

Common situations: Scripts that fetch a process definition version from an untyped map/JSON which returned null; integrations built against older engine APIs where version was inferred; refactoring that dropped a default version constant.

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

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

Appendix: source

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

 * 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) {
            throw new ActivitiObjectNotFoundException("No process instance found for id = '" + processInstanceId + "'.", ProcessInstance.class);
        } else if (!processInstance.isProcessInstanceType()) {
            throw new ActivitiIllegalArgumentException(

View on GitHub (pinned to d6d39ce1c6)