flowable/flowable-engine · error · FlowableException

The deployment contains process definitions with the same ke

Error message

The deployment contains process definitions with the same key '<key>' (process id attribute), this is not allowed

What it means

During deployment, BpmnDeploymentHelper.verifyProcessDefinitionsDoNotShareKeys checks that all process definitions in one deployment have unique keys (the process id attribute in BPMN XML). A duplicate key makes auto-generated activity/definition identifiers ambiguous, so Flowable refuses the deployment with this FlowableException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/deployer/BpmnDeploymentHelper.java:69

import org.flowable.variable.service.impl.el.NoExecutionVariableScope;

/**
 * Methods for working with deployments. Much of the actual work of {@link BpmnDeployer} is done by orchestrating the different pieces of work this class does; by having them here, we allow other
 * deployers to make use of them.
 */
public class BpmnDeploymentHelper {

    /**
     * Verifies that no two process definitions share the same key, to prevent database unique index violation.
     * 
     * @throws FlowableException
     *             if any two processes have the same key
     */
    public void verifyProcessDefinitionsDoNotShareKeys(Collection<ProcessDefinitionEntity> processDefinitions) {
        Set<String> keySet = new LinkedHashSet<>();
        for (ProcessDefinitionEntity processDefinition : processDefinitions) {
            if (keySet.contains(processDefinition.getKey())) {
                throw new FlowableException(
                        "The deployment contains process definitions with the same key '" + processDefinition.getKey() + "' (process id attribute), this is not allowed");
            }
            keySet.add(processDefinition.getKey());
        }
    }

    /**
     * Updates all the process definition entities to match the deployment's values for tenant, engine version, and deployment id.
     */
    public void copyDeploymentValuesToProcessDefinitions(DeploymentEntity deployment,
            List<ProcessDefinitionEntity> processDefinitions) {
        String engineVersion = deployment.getEngineVersion();
        String tenantId = deployment.getTenantId();
        String deploymentId = deployment.getId();

        for (ProcessDefinitionEntity processDefinition : processDefinitions) {

            // Backwards compatibility

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Give each <process> element in the deployment a unique id attribute
  2. Remove duplicate BPMN files from the deployment archive
  3. If the same process must appear twice, differentiate keys and rely on process versioning for new versions
  4. Search the deployment resources for the offending key before deploying to catch it early

Example fix

<!-- before: two files both contain -->
<process id="orderProcess" ...>

<!-- after: rename in one file -->
<process id="refundProcess" ...>
Defensive patterns

Strategy: validation

Validate before calling

Set<String> keys = new HashSet<>();
for (String res : deploymentResources) {
    String id = extractProcessId(res); // parse <process id="...">
    if (!keys.add(id)) {
        throw new IllegalArgumentException("Duplicate process key in deployment: " + id);
    }
}

Prevention

When it happens

Trigger: Deploying a bar/zip (or batch deployment) containing two or more BPMN files whose <process id="..."> attribute has the same value. Hit during RepositoryService.createDeployment().deploy().

Common situations: Copying a BPMN file into a deployment archive without renaming the process id; zip deployments bundling multiple copies of the same diagram; build scripts aggregating resources from several modules that share a process id.

Related errors

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