flowable/flowable-engine · error · FlowableIllegalArgumentException

The current process definition (id = '${currentProcessDefini

Error message

The current process definition (id = '${currentProcessDefinition.getId()}') is a v5 definition. However the new process definition (id = '${newProcessDefinition.getId()}') is not a v5 definition.

What it means

The command refuses to migrate a Flowable 5 process instance to a non-v5 (Flowable 6) process definition, or vice versa in the mixed-engine mode. Version migration must stay within the same engine generation.

Source

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

        // 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.");
        }

        DeploymentManager deploymentCache = CommandContextUtil.getProcessEngineConfiguration(commandContext).getDeploymentManager();
        ProcessDefinition currentProcessDefinition = deploymentCache.findDeployedProcessDefinitionById(processInstance.getProcessDefinitionId());

        ProcessDefinition newProcessDefinition = deploymentCache
                .findDeployedProcessDefinitionByKeyAndVersionAndTenantId(currentProcessDefinition.getKey(), processDefinitionVersion, currentProcessDefinition.getTenantId());

        if (Flowable5Util.isFlowable5ProcessDefinition(currentProcessDefinition, commandContext) && !Flowable5Util
            .isFlowable5ProcessDefinition(newProcessDefinition, commandContext)) {
            throw new FlowableIllegalArgumentException("The current process definition (id = '" + currentProcessDefinition.getId() + "') is a v5 definition."
                + " However the new process definition (id = '" + newProcessDefinition.getId() + "') is not a v5 definition.");
        }

        validateAndSwitchVersionOfExecution(commandContext, processInstance, newProcessDefinition);

        // switch the historic process instance to the new process definition version
        CommandContextUtil.getHistoryManager(commandContext).recordProcessDefinitionChange(processInstanceId, newProcessDefinition.getId());

        // switch all sub-executions of the process instance to the new process definition version
        Collection<ExecutionEntity> childExecutions = executionManager.findChildExecutionsByProcessInstanceId(processInstanceId);
        for (ExecutionEntity executionEntity : childExecutions) {
            validateAndSwitchVersionOfExecution(commandContext, executionEntity, newProcessDefinition);
        }

        return null;
    }

    protected void validateAndSwitchVersionOfExecution(CommandContext commandContext, ExecutionEntity execution, ProcessDefinition newProcessDefinition) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Only migrate between versions of definitions of the same engine generation
Redeploy the target version with Flowable 5 compatibility enabled if the instance is a v5 instance
Complete or terminate v5 instances before switching to v6 definitions; do not use setProcessDefinitionVersion across the v5/v6 boundary

Example fix

// before
new SetProcessDefinitionVersionCmd(piId, 2); // current def v5, target def v6
// after
if (Flowable5Util.isFlowable5ProcessDefinition(currentDef, ctx) == Flowable5Util.isFlowable5ProcessDefinition(newDef, ctx)) {
    new SetProcessDefinitionVersionCmd(piId, 2);
}

Defensive patterns

Strategy: validation

Validate before calling

boolean sameGeneration = Flowable5Util.isFlowable5ProcessDefinition(currentDef, ctx) == Flowable5Util.isFlowable5ProcessDefinition(newDef, ctx);
if (!sameGeneration) throw new IllegalStateException("cannot migrate across v5/v6");

Try / catch

try { cmd.execute(ctx); } catch (FlowableIllegalArgumentException e) { log.error("v5/v6 migration not supported", e); }

Prevention

Check engine generation of both definitions before migration
Pin definition keys to avoid v5/v6 key collisions
Plan v5 instances complete before engine upgrade

When it happens

Trigger: Calling setProcessDefinitionVersion where the current definition is marked as a Flowable 5 definition (deployed via the v5 compatibility layer) and the target version resolves to a Flowable 6 definition (or the new definition key/version resolves to a different engine generation).

Common situations: Upgrading from Flowable 5 / Activiti to Flowable 6 while migrating running v5 instances; deploying a new definition version without the v5 compatibility flag; key collision between a v5 and v6 definition.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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