flowable/flowable-engine · error · FlowableException

Can't deploy a v5 deployment with no flowable 5 compatibilit

Error message

Can't deploy a v5 deployment with no flowable 5 compatibility enabled or no compatibility handler on the classpath

What it means

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.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/DeployCmd.java:66

    protected DeploymentBuilderImpl deploymentBuilder;

    public DeployCmd(DeploymentBuilderImpl deploymentBuilder) {
        this.deploymentBuilder = deploymentBuilder;
    }

    @Override
    public Deployment execute(CommandContext commandContext) {

        // Backwards compatibility with v5
        if (deploymentBuilder.getDeploymentProperties() != null
                && deploymentBuilder.getDeploymentProperties().containsKey(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION)
                && deploymentBuilder.getDeploymentProperties().get(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION).equals(Boolean.TRUE)) {

            ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
            if (processEngineConfiguration.isFlowable5CompatibilityEnabled() && processEngineConfiguration.getFlowable5CompatibilityHandler() != null) {
                return deployAsFlowable5ProcessDefinition(commandContext);
            } else {
                throw new FlowableException("Can't deploy a v5 deployment with no flowable 5 compatibility enabled or no compatibility handler on the classpath");
            }
        }

        return executeDeploy(commandContext);
    }

    protected Deployment executeDeploy(CommandContext commandContext) {
        DeploymentEntity deployment = deploymentBuilder.getDeployment();

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        deployment.setDeploymentTime(processEngineConfiguration.getClock().getCurrentTime());

        if (deploymentBuilder.isDuplicateFilterEnabled()) {

            List<Deployment> existingDeployments = new ArrayList<>();
            if (deployment.getTenantId() == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(deployment.getTenantId())) {
                List<Deployment> deploymentEntities = new DeploymentQueryImpl(processEngineConfiguration.getCommandExecutor())
                        .deploymentName(deployment.getName())

View on GitHub (pinned to d6d39ce1c6)

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.

Example fix

// before
ProcessEngineConfiguration cfg = new StandaloneProcessEngineConfiguration(); // no v5 setup
deploymentBuilder.setProperty(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION, true);
// after
((ProcessEngineConfigurationImpl) cfg).setFlowable5CompatibilityEnabled(true);
classpath += "org.flowable:flowable5-compatibility";
deploymentBuilder.setProperty(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION, true);

Defensive patterns

Strategy: validation

Validate before calling

ProcessEngineConfigurationImpl cfg = ...;
boolean v5Ready = cfg.isFlowable5CompatibilityEnabled() && cfg.getFlowable5CompatibilityHandler() != null;
if (!v5Ready) throw new IllegalStateException("v5 deployment requested but compatibility not configured");

Try / catch

try { deploy(); } catch (FlowableException e) { /* fall back to v6 deploy without the v5 property */ }

Prevention

Add the flowable5-compatibility dependency whenever the v5 flag is used
Assert handler availability during engine startup
Prefer native v6 deployments for new projects

When it happens

Trigger: Creating a deployment with deploymentBuilder.setProperty(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION, true) (or deployAsFlowable5ProcessDefinition()) while processEngineConfiguration.isFlowable5CompatibilityEnabled() is false or flowable5CompatibilityHandler is null.

Common situations: 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.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/1546ec4e55f3928c. Report an issue: GitHub.