{"record":{"id":"cbdfa76b92e2c61c","repo":"flowable/flowable-engine","slug":"found-flowable-5-process-definition-but-no-compat-cbdfa7","errorCode":null,"errorMessage":"Found Flowable 5 process definition, but no compatibility handler on the classpath","messagePattern":"Found Flowable 5 process definition, but no compatibility handler on the classpath","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/Flowable5Util.java","lineNumber":157,"sourceCode":"\n    public static boolean isVersion5Tag(String tag) {\n        return V5_ENGINE_TAG.equals(tag) || \"activiti-5\".equals(tag);\n    }\n\n    public static Flowable5CompatibilityHandler getFlowable5CompatibilityHandler() {\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration();\n\n        Flowable5CompatibilityHandler flowable5CompatibilityHandler = null;\n        if (processEngineConfiguration != null) {\n            flowable5CompatibilityHandler = processEngineConfiguration.getFlowable5CompatibilityHandler();\n        }\n\n        if (flowable5CompatibilityHandler == null) {\n            flowable5CompatibilityHandler = Flowable5CompatibilityContext.getFallbackFlowable5CompatibilityHandler();\n        }\n\n        if (flowable5CompatibilityHandler == null) {\n            throw new FlowableException(\"Found Flowable 5 process definition, but no compatibility handler on the classpath\");\n        }\n        return flowable5CompatibilityHandler;\n    }\n\n}\n","sourceCodeStart":139,"sourceCodeEnd":163,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/Flowable5Util.java#L139-L163","documentation":"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.","triggerScenarios":"Accessing a v5-tagged entity (via getFlowable5CompatibilityHandler called from isV5Entity paths) when neither the configuration nor the classpath provides a Flowable5CompatibilityHandler implementation.","commonSituations":"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.","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."],"exampleFix":"// before (pom.xml): compatibility module missing\n<dependency>\n  <groupId>org.flowable</groupId>\n  <artifactId>flowable-engine</artifactId>\n</dependency>\n\n// after\n<dependency>\n  <groupId>org.flowable</groupId>\n  <artifactId>flowable5-compatibility</artifactId>\n  <version>${flowable.version}</version>\n</dependency>","handlingStrategy":"validation","validationCode":"if (Flowable5CompatibilityContext.getFallbackFlowable5CompatibilityHandler() == null\n        && processEngineConfiguration.getFlowable5CompatibilityHandler() == null) {\n    throw new IllegalStateException(\"Flowable 5 compatibility module missing from classpath\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Flowable5Util.getFlowable5CompatibilityHandler();\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"no compatibility handler\")) {\n        throw new IllegalStateException(\"Add the flowable5-compatibility dependency\", e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["compatibility","classpath","missing-dependency"],"backgroundTag":"missing-dependency","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}