{"record":{"id":"8ca02071ad61c5bb","repo":"flowable/flowable-engine","slug":"found-flowable-5-process-definition-but-no-compat","errorCode":null,"errorMessage":"Found Flowable 5 process definition, but no compatibility handler on the classpath. Cannot use the deployment property ${DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION}","messagePattern":"Found Flowable 5 process definition, but no compatibility handler on the classpath\\. Cannot use the deployment property (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/DeployCmd.java","lineNumber":152,"sourceCode":"        // Actually deploy\n        processEngineConfiguration.getDeploymentManager().deploy(deployment, deploymentSettings);\n\n        if (deploymentBuilder.getProcessDefinitionsActivationDate() != null) {\n            scheduleProcessDefinitionActivation(commandContext, deployment);\n        }\n\n        if (eventDispatcher != null && eventDispatcher.isEnabled()) {\n            eventDispatcher.dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_INITIALIZED, deployment),\n                    processEngineConfiguration.getEngineCfgKey());\n        }\n\n        return deployment;\n    }\n\n    protected Deployment deployAsFlowable5ProcessDefinition(CommandContext commandContext) {\n        Flowable5CompatibilityHandler flowable5CompatibilityHandler = CommandContextUtil.getProcessEngineConfiguration(commandContext).getFlowable5CompatibilityHandler();\n        if (flowable5CompatibilityHandler == null) {\n            throw new FlowableException(\"Found Flowable 5 process definition, but no compatibility handler on the classpath. \"\n                    + \"Cannot use the deployment property \" + DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION);\n        }\n        return flowable5CompatibilityHandler.deploy(deploymentBuilder);\n    }\n\n    protected boolean deploymentsDiffer(DeploymentEntity deployment, DeploymentEntity saved) {\n\n        if (deployment.getResources() == null || saved.getResources() == null) {\n            return true;\n        }\n\n        Map<String, EngineResource> resources = deployment.getResources();\n        Map<String, EngineResource> savedResources = saved.getResources();\n\n        for (String resourceName : resources.keySet()) {\n            EngineResource savedResource = savedResources.get(resourceName);\n\n            if (savedResource == null) {","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/DeployCmd.java#L134-L170","documentation":"deployAsFlowable5ProcessDefinition re-checks the compatibility handler before delegating the deployment. If the handler is null (class missing), even though compatibility may be enabled, the deployment cannot proceed and this FlowableException names the offending deployment property in the message.","triggerScenarios":"Deploying with DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION=true when flowable5CompatibilityHandler was never set on the configuration — typically because the compatibility handler class is absent from the classpath even if the flag is enabled.","commonSituations":"Partial dependency resolution: the flowable5-compatibility jar excluded in shading/proguard; handler bean not wired in Spring configuration; runtime environment (app server) missing the jar the dev environment had.","solutions":["Add the flowable5-compatibility dependency so Flowable5CompatibilityHandlerFactory can instantiate the handler.","Verify the handler resolves: ProcessEngineConfigurationImpl.getFlowable5CompatibilityHandler() != null at startup.","Check shaded jars / app server modules for the excluded compatibility classes.","Remove the v5 deployment property if you actually intend a v6 deployment.","Log the configuration at startup to catch a null handler before deployments are attempted."],"exampleFix":"// before\ncfg.setFlowable5CompatibilityEnabled(true); // handler never installed\ndeploy(properties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION = true);\n// after\ncfg.setFlowable5CompatibilityEnabled(true);\nclasspath includes \"org.flowable:flowable5-compatibility\";\ndeploy(properties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION = true);","handlingStrategy":"fallback","validationCode":"if (cfg.getFlowable5CompatibilityHandler() == null) {\n    // remove DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION and deploy as v6 instead\n}","typeGuard":null,"tryCatchPattern":"try { deployAsV5(); } catch (FlowableException e) { deployAsV6(); }","preventionTips":["Verify compatibility jar presence in shaded/app-server artifacts","Smoke-test a v5 deployment at startup","Keep v5 flag and handler wiring in one place to avoid drift"],"tags":["deployment","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"}