{"record":{"id":"001de1c8da973737","repo":"flowable/flowable-engine","slug":"exception-while-autodeploying-process-definitions-001de1","errorCode":null,"errorMessage":"Exception while autodeploying process definitions for resource {}. This exception can be ignored if the root cause indicates a unique constraint violation, which is typically","messagePattern":"Exception while autodeploying process definitions for resource (.+?)\\. This exception can be ignored if the root cause indicates a unique constraint violation, which is typically","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"modules/flowable-spring/src/main/java/org/flowable/spring/configurator/SingleResourceAutoDeploymentStrategy.java","lineNumber":68,"sourceCode":"    }\n\n    @Override\n    protected void deployResourcesInternal(String deploymentNameHint, Resource[] resources, ProcessEngine engine) {\n        // Create a separate deployment for each resource using the resource name\n        RepositoryService repositoryService = engine.getRepositoryService();\n\n        for (final Resource resource : resources) {\n\n            final String resourceName = determineResourceName(resource);\n            final DeploymentBuilder deploymentBuilder = repositoryService.createDeployment().enableDuplicateFiltering().name(resourceName);\n            addResource(resource, resourceName, deploymentBuilder);\n            try {\n                deploymentBuilder.deploy();\n            } catch (RuntimeException e) {\n                if (isThrowExceptionOnDeploymentFailure()) {\n                    throw e;\n                } else {\n                    LOGGER.warn(\n                        \"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. \",\n                        resource, e);\n                }\n            }\n        }\n    }\n\n}\n","sourceCodeStart":50,"sourceCodeEnd":77,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-spring/src/main/java/org/flowable/spring/configurator/SingleResourceAutoDeploymentStrategy.java#L50-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nprocesses/order.bpmn20.xml with duplicate key 'order' version colliding\n// after: assign unique keys/versions or pre-deploy\n<process id=\"order_v2\" name=\"Order process\" isExecutable=\"true\">","handlingStrategy":"validation","validationCode":"List<Resource> dupes = findDuplicateProcessKeys(resources);\nif (!dupes.isEmpty())\n  throw new IllegalStateException(\"Duplicate process definitions: \" + dupes);","typeGuard":null,"tryCatchPattern":"try {\n  deploymentBuilder.deploy();\n} catch (RuntimeException e) {\n  logger.warn(\"Deployment of {} failed\", resource, e); // inspect cause before deciding to ignore\n  if (!isUniqueConstraintViolation(e)) throw e;\n}","preventionTips":["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."],"tags":["spring","auto-deployment","database","cluster"],"backgroundTag":"database-write-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}