flowable/flowable-engine · critical · FlowableException

Found at least one running v5 process instance. Enable the '

Error message

Found at least one running v5 process instance. Enable the 'flowable5CompatibilityEnabled' property in the process engine configuration and make sure the flowable5-compatibility dependency is available on the classpath

What it means

Thrown at startup when the runtime database still contains running process instances created by the v5 engine while v5 compatibility is disabled. Those instances cannot be executed by the Flowable 6 engine alone, so the engine refuses to start rather than orphan them.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ValidateV5EntitiesCmd.java:73

                    LOGGER.error(message);

                    for (ProcessDefinition processDefinition : processDefinitions) {
                        LOGGER.error("Found v5 process definition with id: {}, and key: {}", processDefinition.getId(), processDefinition.getKey());
                    }

                    throw new FlowableException(message);
                }

                RuntimeService runtimeService = processEngineConfiguration.getRuntimeService();
                long numberOfV5ProcessInstances = runtimeService.createProcessInstanceQuery().processDefinitionEngineVersion(Flowable5Util.V5_ENGINE_TAG).count();

                if (numberOfV5ProcessInstances > 0) {
                    String message = new StringBuilder("Found at least one running v5 process instance.")
                            .append(" Enable the 'flowable5CompatibilityEnabled' property in the process engine configuration")
                            .append(" and make sure the flowable5-compatibility dependency is available on the classpath").toString();
                    LOGGER.error(message);

                    throw new FlowableException(message);
                }
            }
        }

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Enable flowable5CompatibilityEnabled=true and add the flowable5-compatibility dependency so the embedded v5 engine can finish those instances.
Complete or terminate the v5 instances before upgrading (run them to completion on the old engine, or delete them via the v5 API/admin tooling).
Migrate instances using the official Activiti 5 to Flowable 6 migration tooling if continuing on v6 without compatibility is the goal.

Example fix

// before
<property name="flowable5CompatibilityEnabled" value="false"/>
// after
<property name="flowable5CompatibilityEnabled" value="true"/>
<!-- plus: flowable5-compatibility on the classpath -->

Defensive patterns

Strategy: validation

Validate before calling

long v5running = runtimeService.createProcessInstanceQuery().processDefinitionEngineVersion("v5").count(); if (v5running > 0) { /* keep compatibility enabled or drain instances first */ }

Try / catch

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().contains("running v5 process instance")) { /* drain instances or enable compatibility */ } }

Prevention

Drain in-flight v5 instances before cutting over to Flowable 6
Run the v5-compatibility engine during the migration window
Monitor v5 instance counts pre-upgrade as a go/no-go gate

When it happens

Trigger: Engine boot validation finds processInstanceQuery().processDefinitionEngineVersion("v5").count() > 0 while flowable5CompatibilityEnabled is false; typically during an upgrade from Activiti 5/Flowable 5 to Flowable 6+ with in-flight instances.

Common situations: Upgrading a production system mid-flight with long-running v5 instances; switching an app from Flowable 5 to Flowable 6 without adding the compatibility module.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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