{"record":{"id":"5fd14df3173616af","repo":"flowable/flowable-engine","slug":"exception-while-autodeploying-cmmn-definitions-th","errorCode":null,"errorMessage":"Exception while autodeploying CMMN 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 CMMN 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-cmmn-spring/src/main/java/org/flowable/cmmn/spring/autodeployment/DefaultAutoDeploymentStrategy.java","lineNumber":72,"sourceCode":"    protected void deployResourcesInternal(String deploymentNameHint, Resource[] resources, CmmnEngine engine) {\n        CmmnRepositoryService repositoryService = engine.getCmmnRepositoryService();\n\n        // Create a single deployment for all resources using the name hint as the literal name\n        final CmmnDeploymentBuilder deploymentBuilder = repositoryService.createDeployment().enableDuplicateFiltering().name(deploymentNameHint);\n\n        for (final Resource resource : resources) {\n            addResource(resource, deploymentBuilder);\n        }\n\n        try {\n\n            deploymentBuilder.deploy();\n\n        } catch (RuntimeException e) {\n            if (isThrowExceptionOnDeploymentFailure()) {\n                throw e;\n            } else {\n                LOGGER.warn(\"Exception while autodeploying CMMN 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":54,"sourceCodeEnd":81,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-spring/src/main/java/org/flowable/cmmn/spring/autodeployment/DefaultAutoDeploymentStrategy.java#L54-L81","documentation":"DefaultAutoDeploymentStrategy.deployResourcesInternal builds a CMMN deployment and calls deploymentBuilder.deploy(). If that throws a RuntimeException and isThrowExceptionOnDeploymentFailure() is false, the exception is swallowed with this warning; if true, it is rethrown. It exists so concurrent server startups hitting a unique-constraint on the same auto-deployment do not crash every node.","triggerScenarios":"Spring boot auto-deployment of CMMN resources (default strategy) when the database insert fails — most often a unique constraint (ACT_CMMN_DEPLOYMENT) violation from two nodes deploying identical resources simultaneously, or invalid CMMN XML.","commonSituations":"Multiple application instances starting simultaneously against a shared Flowable database; a restart racing with a previous deployment; malformed .cmmn/.cmmn10.xml resources when throwExceptionOnDeploymentFailure is false (error hidden in logs).","solutions":["Read the wrapped root cause in the log to see the actual failure (unique constraint vs XML parse error).","If you want failures to surface, set cmmn.deployment.throwExceptionOnDeploymentFailure (CmmnEngineConfiguration.setThrowExceptionOnDeploymentFailure) to true.","Serialize/avoid concurrent auto-deploys: deploy once during image build or use shared deployment (deploymentMode: single-resource/startup with tenant checks).","If it is the unique-constraint race, it is benign — the other node's deployment wins; verify definitions are present in ACT_CMMN_DEPLOYMENT.","Fix the invalid CMMN resource if the cause is schema/validation failure."],"exampleFix":"// before\n@Bean\npublic EngineConfigurationConfigurer<SpringProcessEngineConfiguration> config() { ... } // silent swallow\ncmmnEngineConfiguration.setThrowExceptionOnDeploymentFailure(false);\n// after\ncmmnEngineConfiguration.setThrowExceptionOnDeploymentFailure(true); // fail fast on bad deployments","handlingStrategy":"retry","validationCode":"// pre-flight: ensure only one node auto-deploys or definitions already exist\nlong count = managementService.executeCommand(ctx ->\n    ctx.getProcessEngineConfiguration().getDeploymentEntityManager()\n       .findDeploymentsByQueryCriteria(new DeploymentQueryImpl().deploymentName(deploymentName))).size();\nif (count > 0) { /* skip auto-deploy */ }","typeGuard":null,"tryCatchPattern":"try {\n    cmmnEngine.run();\n} catch (FlowableException e) {\n    if (e.getCause() instanceof SQLException && e.getMessage().contains(\"unique\")) {\n        LOGGER.info(\"Concurrent auto-deploy detected; continuing\");\n    } else {\n        throw e;\n    }\n}","preventionTips":["Set throwExceptionOnDeploymentFailure=true unless you explicitly need cluster-race tolerance.","Stagger instance startup or use leader election so one node deploys.","Use Flowable's deployment deduplication features (same-deployment auto-deploy modes).","Always log the full exception chain to distinguish constraint races from real errors."],"tags":["auto-deployment","database","concurrency","cmmn"],"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-14T11:17:12.474Z"}