apache/dolphinscheduler · error · ServiceException

UPDATE_ENVIRONMENT_WORKER_GROUP_RELATION_ERROR

UPDATE_ENVIRONMENT_WORKER_GROUP_RELATION_ERROR

Error message

UPDATE_ENVIRONMENT_WORKER_GROUP_RELATION_ERROR

What it means

Thrown by checkUsedEnvironmentWorkerGroupRelation when a worker group being removed from an environment is still referenced by task definitions that run under that environment+workerGroup combination. Deleting the relation would break those tasks, so the update is refused with the list of affected task names.

Source

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

        }

        Environment environment = environmentMapper.queryByEnvironmentName(environmentName);
        if (environment != null) {
            log.warn("Environment with the same name already exist, name:{}.", environment.getName());
            throw new ServiceException(Status.ENVIRONMENT_NAME_EXISTS, environmentName);
        }
    }

    private void checkUsedEnvironmentWorkerGroupRelation(Set<String> deleteKeySet,
                                                         String environmentName, Long environmentCode) {
        for (String workerGroup : deleteKeySet) {
            List<TaskDefinition> taskDefinitionList =
                    taskDefinitionDao.queryByEnvironmentCodeAndWorkerGroup(environmentCode, workerGroup);

            if (Objects.nonNull(taskDefinitionList) && taskDefinitionList.size() != 0) {
                Set<String> collect =
                        taskDefinitionList.stream().map(TaskDefinition::getName).collect(Collectors.toSet());
                throw new ServiceException(Status.UPDATE_ENVIRONMENT_WORKER_GROUP_RELATION_ERROR, workerGroup,
                        environmentName, collect);
            }
        }
    }

    protected void checkParams(String name, String config, String workerGroups) {
        if (StringUtils.isEmpty(name)) {
            throw new ServiceException(Status.ENVIRONMENT_NAME_IS_NULL);
        }
        if (StringUtils.isEmpty(config)) {
            throw new ServiceException(Status.ENVIRONMENT_CONFIG_IS_NULL);
        }
        if (StringUtils.isNotEmpty(workerGroups)) {
            try {
                JSONUtils.parseObject(workerGroups, new TypeReference<List<String>>() {
                });
            } catch (IllegalArgumentException e) {
                throw new ServiceException(Status.ENVIRONMENT_WORKER_GROUPS_IS_INVALID);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Reassign the listed task definitions to another worker group first, then retry the environment update
2. Delete or archive the tasks that reference the removed worker group
3. Keep the worker group in the environment until all dependent tasks are migrated
4. List tasks by environment code and worker group to plan the migration

Example fix

// before
// workerGroups: "[\"groupA\"]" while tasks still use groupA -> throws
// after
// 1) update tasks to workerGroup groupB
// 2) then update environment with workerGroups: "[\"groupB\"]"

for (String group : groupsToRemove) {
    List<TaskDefinition> deps = taskDefinitionDao.queryByEnvironmentCodeAndWorkerGroup(envCode, group);
    if (deps != null && !deps.isEmpty()) {
        throw new IllegalStateException("Worker group " + group + " still used by tasks: "
            + deps.stream().map(TaskDefinition::getName).collect(Collectors.toList()));
    }
}

try {
    environmentService.updateEnvironmentByCode(loginUser, code, name, desc, config, newWorkerGroups);
} catch (ServiceException e) {
    if (e.getCode() == Status.UPDATE_ENVIRONMENT_WORKER_GROUP_RELATION_ERROR.getCode()) {
        // migrate listed tasks to another worker group, then retry
    } else { throw e; }
}

When it happens

Trigger: updateEnvironmentByCode with workerGroups that drop one or more groups, where queryByEnvironmentCodeAndWorkerGroup finds non-empty task definitions still bound to the removed group.

Common situations: Removing a worker group from an environment while tasks still select that group; refactoring worker group names without migrating task definitions; cleaning up decommissioned worker groups that tasks still reference.

Related errors

• ENVIRONMENT_WORKER_GROUPS_IS_INVALID
• DESCRIPTION_TOO_LONG_ERROR
• ENVIRONMENT_NAME_EXISTS
• CREATE_ENVIRONMENT_ERROR
• QUERY_ENVIRONMENT_BY_CODE_ERROR

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