flowable/flowable-engine · critical · FlowableException

Found v5 process definitions that are the latest version. En

Error message

Found v5 process definitions that are the latest version. 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 during engine startup/validation when the database contains v5 (Activiti 5 compatibility) process definitions that are the latest version, but Flowable 6+ compatibility mode is not enabled. Since the v5 engine is not running, those definitions would be unusable, so startup aborts with a FlowableException listing the offending definitions.

Source

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

            LOGGER.info("Total of v5 deployments found: {}", numberOfV5Deployments);

            if (numberOfV5Deployments > 0) {
                List<ProcessDefinition> processDefinitions = repositoryService.createProcessDefinitionQuery()
                        .latestVersion()
                        .processDefinitionEngineVersion(Flowable5Util.V5_ENGINE_TAG)
                        .list();

                if (!processDefinitions.isEmpty()) {
                    String message = new StringBuilder("Found v5 process definitions that are the latest version.")
                            .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);

                    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 compatibility: set flowable5CompatibilityEnabled=true in ProcessEngineConfiguration (or flowable5-compatibility.enabled=true in Spring Boot).
Add the org.flowable:flowable5-compatibility dependency (and flowable5-spring compatibility if using Spring) to the classpath.
If v5 definitions are truly obsolete, deploy a new v6 version of each process (making the v6 row the latest) or archive/clean the v5 definition rows with proper data migration.

Example fix

// before
ProcessEngineConfiguration cfg = ProcessEngineConfiguration.createProcessEngineConfigurationFromResource("flowable.cfg.xml");
// after
cfg.setFlowable5CompatibilityEnabled(true);
// pom.xml: <dependency><groupId>org.flowable</groupId><artifactId>flowable5-compatibility</artifactId><version>...</version></dependency>

Defensive patterns

Strategy: validation

Validate before calling

long v5defs = repositoryService.createProcessDefinitionQuery().processDefinitionEngineVersion("v5").count(); if (v5defs > 0) { enableFlowable5Compatibility(); }

Try / catch

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().contains("v5 process definitions")) { /* enable compatibility and rebuild */ } }

Prevention

Before upgrading from Activiti 5, inventory v5 rows: select * from ACT_RE_PROCDEF where ENGINE_VERSION_ = 'v5'
Deploy new v6 versions of all active processes so latest versions are v6
Keep flowable5-compatibility on the classpath during migration periods

When it happens

Trigger: Starting a Flowable 6+ engine against a database previously used by Activiti 5 / Flowable v5, where ACT_RE_PROCDEF has rows with ENGINE_VERSION_ = 'v5' that are the newest version of their key, while flowable5CompatibilityEnabled is false.

Common situations: Migrating an Activiti 5 production database to Flowable 6; upgrading an old deployment where the last deployed version of a process was v5; reusing a copied production DB against a fresh Flowable 6 install.

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/be849b37a3d36cc7. Report an issue: GitHub.