{"record":{"id":"64b84037fafc7f3e","repo":"apache/dolphinscheduler","slug":"environment-name-exists","errorCode":"ENVIRONMENT_NAME_EXISTS","errorMessage":"Status.ENVIRONMENT_NAME_EXISTS","messagePattern":"Status\\.ENVIRONMENT_NAME_EXISTS","errorType":"error_code","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/EnvironmentServiceImpl.java","lineNumber":111,"sourceCode":"     */\n    @Override\n    @Transactional\n    public Long createEnvironment(User loginUser,\n                                  String name,\n                                  String config,\n                                  String desc,\n                                  String workerGroups) {\n        if (!canOperatorPermissions(loginUser, null, AuthorizationType.ENVIRONMENT, ENVIRONMENT_CREATE)) {\n            throw new ServiceException(Status.USER_NO_OPERATION_PERM);\n        }\n        if (checkDescriptionLength(desc)) {\n            throw new ServiceException(Status.DESCRIPTION_TOO_LONG_ERROR);\n        }\n        checkParams(name, config, workerGroups);\n\n        Environment environment = environmentMapper.queryByEnvironmentName(name);\n        if (environment != null) {\n            throw new ServiceException(Status.ENVIRONMENT_NAME_EXISTS, name);\n        }\n\n        Environment env = new Environment();\n        env.setName(name);\n        env.setConfig(config);\n        env.setDescription(desc);\n        env.setOperator(loginUser.getId());\n        env.setCreateTime(new Date());\n        env.setUpdateTime(new Date());\n        env.setCode(CodeGenerateUtils.genCode());\n\n        if (environmentMapper.insert(env) > 0) {\n            if (!StringUtils.isEmpty(workerGroups)) {\n                List<String> workerGroupList = JSONUtils.parseObject(workerGroups, new TypeReference<List<String>>() {\n                });\n                if (CollectionUtils.isNotEmpty(workerGroupList)) {\n                    workerGroupList.stream().forEach(workerGroup -> {\n                        if (!StringUtils.isEmpty(workerGroup)) {","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/EnvironmentServiceImpl.java#L93-L129","documentation":"Thrown by EnvironmentServiceImpl.createEnvironment when an environment with the same name already exists (environmentMapper.queryByEnvironmentName returns non-null). Environment names must be unique across the installation, so a duplicate create is rejected. The exception message includes the conflicting name.","triggerScenarios":"POST /dolphinscheduler/environments with a 'name' that matches an existing environment row; retrying a create after a partially successful prior attempt; concurrent creation of the same name by two clients before either commits.","commonSituations":"Re-running provisioning scripts that assume create is idempotent; users re-submitting a form after a timeout without realizing the first insert succeeded; name collisions in shared clusters.","solutions":["Query the existing environment first (GET /dolphinscheduler/environments/list or queryEnvironmentByName) and use updateEnvironmentByCode instead of create.","Choose a different, unique environment name.","If the name should be reusable, delete the stale environment first (ensuring no task definitions reference it), then create."],"exampleFix":"// before\nLong code = environmentService.createEnvironment(loginUser, \"default\", config, desc, workerGroups); // may throw\n// after\nEnvironmentDto existing = environmentService.queryEnvironmentByNameOrNull(\"default\");\nLong code = (existing != null)\n        ? existing.getCode()\n        : environmentService.createEnvironment(loginUser, \"default\", config, desc, workerGroups);","handlingStrategy":"validation","validationCode":"EnvironmentDto existing = null;\ntry { existing = environmentService.queryEnvironmentByName(name); } catch (ServiceException ignored) {}\nif (existing != null) {\n    throw new IllegalStateException(\"Environment '\" + name + \"' already exists, code=\" + existing.getCode());\n}","typeGuard":null,"tryCatchPattern":"try {\n    environmentService.createEnvironment(loginUser, name, config, desc, workerGroups);\n} catch (ServiceException e) {\n    if (String.valueOf(e.getMessage()).contains(\"ENVIRONMENT_NAME_EXISTS\")) {\n        // fall back to update or reuse the existing code\n    }\n}","preventionTips":["Check name existence before create and route to update instead","Make provisioning scripts idempotent: fetch-or-create pattern","Use deterministic, unique environment names per cluster/stage"],"tags":["dolphinscheduler","duplicate","uniqueness","environment"],"backgroundTag":"file-already-exists","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}