Exception while autodeploying process definitions. This…

Error message

Exception while autodeploying process definitions. This exception can be ignored if the root cause indicates a unique constraint violation, which is typically caused by two (or more) servers booting up at the exact same time and deploying the same definitions.

What it means

DefaultAutoDeploymentStrategy deploys all matching Spring resources on engine startup. If deploymentBuilder.deploy() throws a RuntimeException and the engine is not configured to throw on deployment failure, the exception is logged with this message instead of failing boot, because a common cause is a transient unique-constraint race when several servers boot simultaneously.

Solutions

Inspect the logged root-cause exception to confirm whether it is a unique constraint violation (safe to ignore) or a real deployment error.
Set flowable.check-process-definitions=false or the strategy's throwExceptionOnDeploymentFailure=true if you want startup to fail fast on real errors.
For clusters, use a shared database with the same deployment resources — the constraint race resolves itself; restart if definitions are missing.
Fix invalid BPMN resources when the root cause is a validation error rather than a constraint violation.

Example fix

// before
spring.flowable.deployment-mode=default // swallows failures
// after: fail fast on real errors
spring.flowable.check-process-definitions=true
@Bean
EngineConfigurationConfigurer<SpringProcessEngineConfiguration> failFast() {
  return cfg -> cfg.setThrowExceptionOnDeploymentFailure(true);
}

Defensive patterns

Strategy: try-catch

Validate before calling

try {
  repositoryService.createDeploymentQuery().deploymentName("auto").list();
} catch (RuntimeException e) {
  // DB unreachable — fix datasource before auto-deploy races occur
}

Try / catch

try {
  deploymentBuilder.deploy();
} catch (RuntimeException e) {
  if (e.getCause() instanceof SQLIntegrityConstraintViolationException) {
    logger.info("Concurrent identical deployment — safe to ignore");
  } else { throw e; }
}

Prevention

Pre-deploy definitions in CI/CD instead of at boot on every replica.
Check the logged root cause: unique-constraint = benign, validation = fix the BPMN.
Set throwExceptionOnDeploymentFailure=true in single-node environments.

When it happens

Trigger: Application startup with flowable auto-deployment enabled and deploymentBuilder.deploy() throwing RuntimeException (e.g. FlowableOptimisticLockingException or duplicate key on ACT_GE_BYTEARRAY/ACT_RE_PROCDEF) while isThrowExceptionOnDeploymentFailure() is false.

Common situations: Multiple cluster nodes starting simultaneously and deploying identical process definitions; database unique constraint violations on process definition keys; malformed BPMN causing deploy-time validation failure swallowed at startup.

Related errors

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

Appendix: source

Thrown at modules/flowable-spring/src/main/java/org/flowable/spring/configurator/DefaultAutoDeploymentStrategy.java:70

    @Override
    protected void deployResourcesInternal(String deploymentNameHint, Resource[] resources, ProcessEngine engine) {
        RepositoryService repositoryService = engine.getRepositoryService();

        // Create a single deployment for all resources using the name hint as the literal name
        final DeploymentBuilder deploymentBuilder = repositoryService.createDeployment().enableDuplicateFiltering().name(deploymentNameHint);

        for (final Resource resource : resources) {
            addResource(resource, deploymentBuilder);
        }

        try {
            deploymentBuilder.deploy();
        } catch (RuntimeException e) {
            if (isThrowExceptionOnDeploymentFailure()) {
                throw e;
            } else {
                LOGGER.warn("Exception while autodeploying process definitions. "
                    + "This exception can be ignored if the root cause indicates a unique constraint violation, "
                    + "which is typically caused by two (or more) servers booting up at the exact same time and deploying the same definitions. ", e);
            }
        }

    }

}

View on GitHub (pinned to d6d39ce1c6)