{"record":{"id":"3bc77c3d61c53d39","repo":"flowable/flowable-engine","slug":"exception-while-autodeploying-process-definitions-3bc77c","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/ResourceParentFolderAutoDeploymentStrategy.java","lineNumber":83,"sourceCode":"        RepositoryService repositoryService = engine.getRepositoryService();\n        // Create a deployment for each distinct parent folder using the namehint as a prefix\n        final Map<String, Set<Resource>> resourcesMap = createMap(resources);\n        for (final Entry<String, Set<Resource>> group : resourcesMap.entrySet()) {\n\n            final String deploymentName = determineDeploymentName(deploymentNameHint, group.getKey());\n            final DeploymentBuilder deploymentBuilder = repositoryService.createDeployment().enableDuplicateFiltering().name(deploymentName);\n\n            for (final Resource resource : group.getValue()) {\n                addResource(resource, deploymentBuilder);\n            }\n\n            try {\n                deploymentBuilder.deploy();\n            } catch (Exception 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    private Map<String, Set<Resource>> createMap(final Resource[] resources) {\n        final Map<String, Set<Resource>> resourcesMap = new HashMap<>();\n\n        for (final Resource resource : resources) {\n            final String parentFolderName = determineGroupName(resource);\n            if (resourcesMap.get(parentFolderName) == null) {\n                resourcesMap.put(parentFolderName, new HashSet<>());\n            }\n            resourcesMap.get(parentFolderName).add(resource);\n        }","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-spring/src/main/java/org/flowable/spring/configurator/ResourceParentFolderAutoDeploymentStrategy.java#L65-L101","documentation":"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.","triggerScenarios":"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.","commonSituations":"Kubernetes/cluster rollout where several replicas boot against the same DB with the same resources folder; duplicate process definition keys across deployments.","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."],"exampleFix":"// before\nspring.flowable.deployment-mode=resource-parent-folder // failures logged only\n// after\n@Configuration\nclass FlowableCfg {\n  @Bean\n  EngineConfigurationConfigurer<SpringProcessEngineConfiguration> strict() {\n    return c -> c.setDeploymentModes(...) // or set throwExceptionOnDeploymentFailure(true) on the strategy\n  }\n}","handlingStrategy":"try-catch","validationCode":"// ensure parent folder resources are unique before deployment\nSet<String> keys = resources.stream()\n  .map(r -> parseProcessKey(r))\n  .collect(toSet());\nif (keys.size() != resources.size()) throw new IllegalStateException(\"duplicate process keys in folder\");","typeGuard":null,"tryCatchPattern":"try {\n  deploymentBuilder.deploy();\n} catch (Exception e) {\n  if (!isUniqueConstraint(e)) throw e; // rethrow real errors\n  logger.info(\"Concurrent deployment race on parent folder resources — ignored\");\n}","preventionTips":["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."],"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"}