{"record":{"id":"1546ec4e55f3928c","repo":"flowable/flowable-engine","slug":"can-t-deploy-a-v5-deployment-with-no-flowable-5-co","errorCode":null,"errorMessage":"Can't deploy a v5 deployment with no flowable 5 compatibility enabled or no compatibility handler on the classpath","messagePattern":"Can't deploy a v5 deployment with no flowable 5 compatibility enabled or 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/cmd/DeployCmd.java","lineNumber":66,"sourceCode":"    protected DeploymentBuilderImpl deploymentBuilder;\n\n    public DeployCmd(DeploymentBuilderImpl deploymentBuilder) {\n        this.deploymentBuilder = deploymentBuilder;\n    }\n\n    @Override\n    public Deployment execute(CommandContext commandContext) {\n\n        // Backwards compatibility with v5\n        if (deploymentBuilder.getDeploymentProperties() != null\n                && deploymentBuilder.getDeploymentProperties().containsKey(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION)\n                && deploymentBuilder.getDeploymentProperties().get(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION).equals(Boolean.TRUE)) {\n\n            ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n            if (processEngineConfiguration.isFlowable5CompatibilityEnabled() && processEngineConfiguration.getFlowable5CompatibilityHandler() != null) {\n                return deployAsFlowable5ProcessDefinition(commandContext);\n            } else {\n                throw new FlowableException(\"Can't deploy a v5 deployment with no flowable 5 compatibility enabled or no compatibility handler on the classpath\");\n            }\n        }\n\n        return executeDeploy(commandContext);\n    }\n\n    protected Deployment executeDeploy(CommandContext commandContext) {\n        DeploymentEntity deployment = deploymentBuilder.getDeployment();\n\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n        deployment.setDeploymentTime(processEngineConfiguration.getClock().getCurrentTime());\n\n        if (deploymentBuilder.isDuplicateFilterEnabled()) {\n\n            List<Deployment> existingDeployments = new ArrayList<>();\n            if (deployment.getTenantId() == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(deployment.getTenantId())) {\n                List<Deployment> deploymentEntities = new DeploymentQueryImpl(processEngineConfiguration.getCommandExecutor())\n                        .deploymentName(deployment.getName())","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/DeployCmd.java#L48-L84","documentation":"DeployCmd supports deploying Flowable 5 process definitions only when the v5 compatibility mode is enabled AND a Flowable5CompatibilityHandler implementation is on the classpath. When a deployment is marked with DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION=true but either condition fails, this FlowableException is thrown.","triggerScenarios":"Creating a deployment with deploymentBuilder.setProperty(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION, true) (or deployAsFlowable5ProcessDefinition()) while processEngineConfiguration.isFlowable5CompatibilityEnabled() is false or flowable5CompatibilityHandler is null.","commonSituations":"Upgraded Flowable 5 projects whose BPMN files are still deployed with the v5 flag; adding the property via configuration/tooling without adding flowable5-compatibility dependency; forgetting to set flowable5CompatibilityEnabled in the engine configuration.","solutions":["Add the flowable5-compatibility module to the classpath (it provides Flowable5CompatibilityHandler).","Set flowable5CompatibilityEnabled(true) (and the handler) on ProcessEngineConfiguration.","Remove the DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION property and redeploy the BPMN as a native Flowable 6 definition.","Migrate the processes to v6 BPMN so the v5 flag is unnecessary."],"exampleFix":"// before\nProcessEngineConfiguration cfg = new StandaloneProcessEngineConfiguration(); // no v5 setup\ndeploymentBuilder.setProperty(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION, true);\n// after\n((ProcessEngineConfigurationImpl) cfg).setFlowable5CompatibilityEnabled(true);\nclasspath += \"org.flowable:flowable5-compatibility\";\ndeploymentBuilder.setProperty(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION, true);","handlingStrategy":"validation","validationCode":"ProcessEngineConfigurationImpl cfg = ...;\nboolean v5Ready = cfg.isFlowable5CompatibilityEnabled() && cfg.getFlowable5CompatibilityHandler() != null;\nif (!v5Ready) throw new IllegalStateException(\"v5 deployment requested but compatibility not configured\");","typeGuard":null,"tryCatchPattern":"try { deploy(); } catch (FlowableException e) { /* fall back to v6 deploy without the v5 property */ }","preventionTips":["Add the flowable5-compatibility dependency whenever the v5 flag is used","Assert handler availability during engine startup","Prefer native v6 deployments for new projects"],"tags":["deployment","compatibility","flowable5","configuration"],"backgroundTag":"feature-not-enabled","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"}