flowable/flowable-engine · error · FlowableException

Found Flowable 5 process definition, but no compatibility ha

Error message

Found Flowable 5 process definition, but no compatibility handler on the classpath

What it means

When a Flowable 5 process definition/deployment is detected, the engine needs a Flowable5CompatibilityHandler to execute it. getFlowable5CompatibilityHandler first checks the configuration and then falls back to the classpath (Flowable5CompatibilityContext.getFallbackFlowable5CompatibilityHandler()); if both are absent it throws this FlowableException because v5 definitions cannot be handled at all.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/Flowable5Util.java:157

    public static boolean isVersion5Tag(String tag) {
        return V5_ENGINE_TAG.equals(tag) || "activiti-5".equals(tag);
    }

    public static Flowable5CompatibilityHandler getFlowable5CompatibilityHandler() {
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration();

        Flowable5CompatibilityHandler flowable5CompatibilityHandler = null;
        if (processEngineConfiguration != null) {
            flowable5CompatibilityHandler = processEngineConfiguration.getFlowable5CompatibilityHandler();
        }

        if (flowable5CompatibilityHandler == null) {
            flowable5CompatibilityHandler = Flowable5CompatibilityContext.getFallbackFlowable5CompatibilityHandler();
        }

        if (flowable5CompatibilityHandler == null) {
            throw new FlowableException("Found Flowable 5 process definition, but no compatibility handler on the classpath");
        }
        return flowable5CompatibilityHandler;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Add the flowable5-compatibility dependency (org.flowable:flowable5-compatibility or flowable-engine-flowable5-compatibility per version) to the classpath.
Explicitly set flowable5CompatibilityHandler on the ProcessEngineConfiguration.
Redeploy the affected processes as Flowable 6 definitions and remove the v5 deployments.
Check the packaged jar for the fallback registration file so shading does not remove it.

Example fix

// before (pom.xml): compatibility module missing
<dependency>
  <groupId>org.flowable</groupId>
  <artifactId>flowable-engine</artifactId>
</dependency>

// after
<dependency>
  <groupId>org.flowable</groupId>
  <artifactId>flowable5-compatibility</artifactId>
  <version>${flowable.version}</version>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

if (Flowable5CompatibilityContext.getFallbackFlowable5CompatibilityHandler() == null
        && processEngineConfiguration.getFlowable5CompatibilityHandler() == null) {
    throw new IllegalStateException("Flowable 5 compatibility module missing from classpath");
}

Try / catch

try {
    Flowable5Util.getFlowable5CompatibilityHandler();
} catch (FlowableException e) {
    if (e.getMessage().contains("no compatibility handler")) {
        throw new IllegalStateException("Add the flowable5-compatibility dependency", e);
    }
    throw e;
}

Prevention

Add flowable5-compatibility to the dependency list whenever legacy Activiti deployments may exist
Set the handler explicitly in the engine configuration rather than relying on classpath fallback
Check shading/proguard keeps the fallback handler registration resource

When it happens

Trigger: Accessing a v5-tagged entity (via getFlowable5CompatibilityHandler called from isV5Entity paths) when neither the configuration nor the classpath provides a Flowable5CompatibilityHandler implementation.

Common situations: flowable-engine-flowable5-compatibility JAR not on the classpath; v5 deployments present in the database after migrating to Flowable 6 without adding the compatibility module; shading/proguard stripping the fallback handler registration.

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