{"record":{"id":"26cb8467254a1f78","repo":"flowable/flowable-engine","slug":"exception-while-autodeploying-process-definitions","errorCode":null,"errorMessage":"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. ","messagePattern":"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\\. ","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"modules/flowable-spring/src/main/java/org/flowable/spring/configurator/DefaultAutoDeploymentStrategy.java","lineNumber":70,"sourceCode":"\n    @Override\n    protected void deployResourcesInternal(String deploymentNameHint, Resource[] resources, ProcessEngine engine) {\n        RepositoryService repositoryService = engine.getRepositoryService();\n\n        // Create a single deployment for all resources using the name hint as the literal name\n        final DeploymentBuilder deploymentBuilder = repositoryService.createDeployment().enableDuplicateFiltering().name(deploymentNameHint);\n\n        for (final Resource resource : resources) {\n            addResource(resource, deploymentBuilder);\n        }\n\n        try {\n            deploymentBuilder.deploy();\n        } catch (RuntimeException e) {\n            if (isThrowExceptionOnDeploymentFailure()) {\n                throw e;\n            } else {\n                LOGGER.warn(\"Exception while autodeploying process definitions. \"\n                    + \"This exception can be ignored if the root cause indicates a unique constraint violation, \"\n                    + \"which is typically caused by two (or more) servers booting up at the exact same time and deploying the same definitions. \", e);\n            }\n        }\n\n    }\n\n}\n","sourceCodeStart":52,"sourceCodeEnd":79,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-spring/src/main/java/org/flowable/spring/configurator/DefaultAutoDeploymentStrategy.java#L52-L79","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nspring.flowable.deployment-mode=default // swallows failures\n// after: fail fast on real errors\nspring.flowable.check-process-definitions=true\n@Bean\nEngineConfigurationConfigurer<SpringProcessEngineConfiguration> failFast() {\n  return cfg -> cfg.setThrowExceptionOnDeploymentFailure(true);\n}","handlingStrategy":"try-catch","validationCode":"try {\n  repositoryService.createDeploymentQuery().deploymentName(\"auto\").list();\n} catch (RuntimeException e) {\n  // DB unreachable — fix datasource before auto-deploy races occur\n}","typeGuard":null,"tryCatchPattern":"try {\n  deploymentBuilder.deploy();\n} catch (RuntimeException e) {\n  if (e.getCause() instanceof SQLIntegrityConstraintViolationException) {\n    logger.info(\"Concurrent identical deployment — safe to ignore\");\n  } else { throw e; }\n}","preventionTips":["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."],"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"}