What causes "Status.ENVIRONMENT_NAME_EXISTS" in apache/dolphinscheduler?

Query the existing environment first (GET /dolphinscheduler/environments/list or queryEnvironmentByName) and use updateEnvironmentByCode instead of create.

apache/dolphinscheduler · error · ServiceException

ENVIRONMENT_NAME_EXISTS

ENVIRONMENT_NAME_EXISTS

Error message

Status.ENVIRONMENT_NAME_EXISTS

What it means

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.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/EnvironmentServiceImpl.java:111

     */
    @Override
    @Transactional
    public Long createEnvironment(User loginUser,
                                  String name,
                                  String config,
                                  String desc,
                                  String workerGroups) {
        if (!canOperatorPermissions(loginUser, null, AuthorizationType.ENVIRONMENT, ENVIRONMENT_CREATE)) {
            throw new ServiceException(Status.USER_NO_OPERATION_PERM);
        }
        if (checkDescriptionLength(desc)) {
            throw new ServiceException(Status.DESCRIPTION_TOO_LONG_ERROR);
        }
        checkParams(name, config, workerGroups);

        Environment environment = environmentMapper.queryByEnvironmentName(name);
        if (environment != null) {
            throw new ServiceException(Status.ENVIRONMENT_NAME_EXISTS, name);
        }

        Environment env = new Environment();
        env.setName(name);
        env.setConfig(config);
        env.setDescription(desc);
        env.setOperator(loginUser.getId());
        env.setCreateTime(new Date());
        env.setUpdateTime(new Date());
        env.setCode(CodeGenerateUtils.genCode());

        if (environmentMapper.insert(env) > 0) {
            if (!StringUtils.isEmpty(workerGroups)) {
                List<String> workerGroupList = JSONUtils.parseObject(workerGroups, new TypeReference<List<String>>() {
                });
                if (CollectionUtils.isNotEmpty(workerGroupList)) {
                    workerGroupList.stream().forEach(workerGroup -> {
                        if (!StringUtils.isEmpty(workerGroup)) {

View on GitHub (pinned to 02eac45a1b)

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.

Example fix

// before
Long code = environmentService.createEnvironment(loginUser, "default", config, desc, workerGroups); // may throw
// after
EnvironmentDto existing = environmentService.queryEnvironmentByNameOrNull("default");
Long code = (existing != null)
        ? existing.getCode()
        : environmentService.createEnvironment(loginUser, "default", config, desc, workerGroups);

Defensive patterns

Strategy: validation

Validate before calling

EnvironmentDto existing = null;
try { existing = environmentService.queryEnvironmentByName(name); } catch (ServiceException ignored) {}
if (existing != null) {
    throw new IllegalStateException("Environment '" + name + "' already exists, code=" + existing.getCode());
}

Try / catch

try {
    environmentService.createEnvironment(loginUser, name, config, desc, workerGroups);
} catch (ServiceException e) {
    if (String.valueOf(e.getMessage()).contains("ENVIRONMENT_NAME_EXISTS")) {
        // fall back to update or reuse the existing code
    }
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/64b84037fafc7f3e. Report an issue: GitHub.