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

ResourceParentFolderAutoDeploymentStrategy deploys all resources sharing a parent folder as one deployment. If deploymentBuilder.deploy() throws and throwExceptionOnDeploymentFailure is false, the exception is logged with this warning, tolerating unique-constraint races from simultaneous server boots.

Solutions

Check the logged cause: unique-constraint violation is benign; other errors need fixing.
Configure throwExceptionOnDeploymentFailure=true to fail startup on genuine errors.
Pre-deploy definitions via a migration/init job so replicas don't race at boot.
Ensure resources sharing a parent folder don't declare conflicting process definition keys.

Example fix

// before
spring.flowable.deployment-mode=resource-parent-folder // failures logged only
// after
@Configuration
class FlowableCfg {
  @Bean
  EngineConfigurationConfigurer<SpringProcessEngineConfiguration> strict() {
    return c -> c.setDeploymentModes(...) // or set throwExceptionOnDeploymentFailure(true) on the strategy
  }
}

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure parent folder resources are unique before deployment
Set<String> keys = resources.stream()
  .map(r -> parseProcessKey(r))
  .collect(toSet());
if (keys.size() != resources.size()) throw new IllegalStateException("duplicate process keys in folder");

Try / catch

try {
  deploymentBuilder.deploy();
} catch (Exception e) {
  if (!isUniqueConstraint(e)) throw e; // rethrow real errors
  logger.info("Concurrent deployment race on parent folder resources — ignored");
}

Prevention

Avoid multiple replicas deploying the same resources folder simultaneously.
Inspect the logged cause to distinguish constraint races from validation errors.
Keep process definition keys unique within a parent folder.

When it happens

Trigger: Startup auto-deployment (deployment-mode=resource-parent-folder) where deploymentBuilder.deploy() throws Exception — typically a duplicate-key constraint on ACT_GE_BYTEARRAY/ACT_RE_PROCDEF because multiple nodes deployed the same parent-folder resources concurrently.

Common situations: Kubernetes/cluster rollout where several replicas boot against the same DB with the same resources folder; duplicate process definition keys across deployments.

Related errors

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

Appendix: source

Thrown at modules/flowable-spring/src/main/java/org/flowable/spring/configurator/ResourceParentFolderAutoDeploymentStrategy.java:83

        RepositoryService repositoryService = engine.getRepositoryService();
        // Create a deployment for each distinct parent folder using the namehint as a prefix
        final Map<String, Set<Resource>> resourcesMap = createMap(resources);
        for (final Entry<String, Set<Resource>> group : resourcesMap.entrySet()) {

            final String deploymentName = determineDeploymentName(deploymentNameHint, group.getKey());
            final DeploymentBuilder deploymentBuilder = repositoryService.createDeployment().enableDuplicateFiltering().name(deploymentName);

            for (final Resource resource : group.getValue()) {
                addResource(resource, deploymentBuilder);
            }

            try {
                deploymentBuilder.deploy();
            } catch (Exception 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);
                }
            }
        }

    }

    private Map<String, Set<Resource>> createMap(final Resource[] resources) {
        final Map<String, Set<Resource>> resourcesMap = new HashMap<>();

        for (final Resource resource : resources) {
            final String parentFolderName = determineGroupName(resource);
            if (resourcesMap.get(parentFolderName) == null) {
                resourcesMap.put(parentFolderName, new HashSet<>());
            }
            resourcesMap.get(parentFolderName).add(resource);
        }

View on GitHub (pinned to d6d39ce1c6)