flowable/flowable-engine · error · FlowableIllegalArgumentException

The process definition version must be positive, but

Error message

The process definition version must be positive, but '${processDefinitionVersion}' has been provided.

What it means

SetProcessDefinitionVersionCmd's constructor validates its inputs before running the command. When the supplied processDefinitionVersion is less than 1 (e.g. 0 or negative), it throws FlowableIllegalArgumentException because process definition versions in Flowable start at 1.

Solutions

1. Verify the version value passed to the constructor is >= 1 before constructing the command
2. Fix the upstream source of the version (DB column, config, API response) so it holds a real version number
3. If the version is unknown, fetch the current version from the process instance's processDefinitionId instead of guessing

Example fix

// before
int version = 0;
managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));
// after
if (version >= 1) {
    managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));
}

if (version == null || version < 1) throw new IllegalArgumentException("version must be >= 1");

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

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

When it happens

Trigger: Calling new SetProcessDefinitionVersionCmd(processInstanceId, version) with version = 0, a negative number, or an uninitialized Integer default of 0.

Common situations: Passing a zero-initialized version variable from a config or DB record where the version was never populated; integer arithmetic that subtracts from a version; parsing a version string that yields 0.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• The process definition id is mandatory, but
• Invalid JSON expression to parse
• Invalid task id : null
• process definition id is null
• process definition id is null

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

Appendix: source

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

 * @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 " + "'"
                    + processInstance.getProcessInstanceId() + "'. " + "Please invoke the " + getClass().getSimpleName() + " with a root execution id.");
        }

View on GitHub (pinned to d6d39ce1c6)