Exception while autodeploying process definitions for…

Error message

Exception while autodeploying process definitions for resource {}. This exception can be ignored if the root cause indicates a unique constraint violation, which is typically

What it means

SingleResourceAutoDeploymentStrategy deploys each matched resource individually at engine startup. A RuntimeException from deploymentBuilder.deploy() is rethrown only if throwExceptionOnDeploymentFailure is true; otherwise it's logged with this per-resource warning, tolerating the unique-constraint race of simultaneous multi-server boots.

Solutions

Identify which resource failed (the { } placeholder in the log) and inspect the nested exception.
Treat unique-constraint violations as benign; fix or remove resources whose root cause is BPMN validation failure.
Set the strategy's throwExceptionOnDeploymentFailure=true for fail-fast startup in non-racy environments.
Serialize deployments: pre-deploy via CI/CD so app boot doesn't race other nodes.

Example fix

// before
processes/order.bpmn20.xml with duplicate key 'order' version colliding
// after: assign unique keys/versions or pre-deploy
<process id="order_v2" name="Order process" isExecutable="true">

Defensive patterns

Strategy: validation

Validate before calling

List<Resource> dupes = findDuplicateProcessKeys(resources);
if (!dupes.isEmpty())
  throw new IllegalStateException("Duplicate process definitions: " + dupes);

Try / catch

try {
  deploymentBuilder.deploy();
} catch (RuntimeException e) {
  logger.warn("Deployment of {} failed", resource, e); // inspect cause before deciding to ignore
  if (!isUniqueConstraintViolation(e)) throw e;
}

Prevention

Give each BPMN resource a unique process definition key and stable versioning.
Deploy once from a single init job rather than from every booting node.
Read the resource name in the log message to target the failing file.

When it happens

Trigger: Startup with deployment-mode=single-resource where deploying one resource (deploymentBuilder.deploy()) throws RuntimeException — commonly a duplicate process-definition key/constraint violation because another node deployed the same resource at the same moment.

Common situations: Clustered Spring Boot apps starting in parallel against one Flowable DB; re-deploying unchanged BPMN files with definition key/version collisions; invalid BPMN resource mixed among valid ones.

Related errors

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

Appendix: source

Thrown at modules/flowable-spring/src/main/java/org/flowable/spring/configurator/SingleResourceAutoDeploymentStrategy.java:68

    }

    @Override
    protected void deployResourcesInternal(String deploymentNameHint, Resource[] resources, ProcessEngine engine) {
        // Create a separate deployment for each resource using the resource name
        RepositoryService repositoryService = engine.getRepositoryService();

        for (final Resource resource : resources) {

            final String resourceName = determineResourceName(resource);
            final DeploymentBuilder deploymentBuilder = repositoryService.createDeployment().enableDuplicateFiltering().name(resourceName);
            addResource(resource, resourceName, deploymentBuilder);
            try {
                deploymentBuilder.deploy();
            } catch (RuntimeException e) {
                if (isThrowExceptionOnDeploymentFailure()) {
                    throw e;
                } else {
                    LOGGER.warn(
                        "Exception while autodeploying process definitions for resource {}. 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. ",
                        resource, e);
                }
            }
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)