flowable/flowable-engine · error · FlowableIllegalArgumentException

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's constructor throws this FlowableIllegalArgumentException when processDefinitionVersion is null. Both arguments are mandatory and validated up front; a null version means the command cannot determine which definition version to migrate the instance to. The constructor fails before any state is assigned.

Source

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

 * 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) {
            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 " + "'"

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resolve the version explicitly (e.g. from RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getVersion()) before constructing the command
2. Null-check the version at your call site and fail with a clear message
3. Provide a sensible default version if the business case allows

Example fix

// before
Integer version = config.get("targetVersion"); // may be null
managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));
// after
ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("order").latestVersion().singleResult();
managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, def.getVersion()));

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

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

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

When it happens

Trigger: Constructing new SetProcessDefinitionVersionCmd(processInstanceId, null), typically when the version was read from an unset Integer variable, an absent config field, or the result of an unboxing/null return from a query.

Common situations: Integer processDefinitionVersion = map.get("version") returning null when the key is missing; autoboxing null from a database column; refactoring replaced a literal with a nullable variable.

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
• Process definition id or key cannot be null

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