apache/dolphinscheduler · error · ServiceException

1401002

1401002

Error message

You can not modify or remove this worker group, cause it has [{0}] dependent environments.

What it means

Thrown by checkWorkerGroupDependencies in WorkerGroupServiceImpl when a worker group cannot be deleted because one or more environments still reference it (rows exist in the environment-worker-group relation table). DolphinScheduler refuses the delete to avoid leaving environments pointing at a nonexistent worker group. The message includes the count of dependent environments.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/WorkerGroupServiceImpl.java:188

        // check if the worker group has any dependent schedulers
        List<Schedule> schedules = scheduleDao.queryScheduleByWorkerGroup(workerGroup.getName());

        if (CollectionUtils.isNotEmpty(schedules)) {
            List<String> workflowDefinitionNames = schedules.stream().limit(3)
                    .map(schedule -> workflowDefinitionDao.queryByCode(schedule.getWorkflowDefinitionCode())
                            .orElse(null).getName())
                    .collect(Collectors.toList());
            throw new ServiceException(Status.WORKER_GROUP_DEPENDENT_SCHEDULER_EXISTS, schedules.size(),
                    JSONUtils.toJsonString(workflowDefinitionNames));
        }

        // check if the worker group has any dependent environments
        List<EnvironmentWorkerGroupRelation> environmentWorkerGroupRelations =
                environmentWorkerGroupRelationMapper.selectList(new QueryWrapper<EnvironmentWorkerGroupRelation>()
                        .lambda().eq(EnvironmentWorkerGroupRelation::getWorkerGroup, workerGroup.getName()));

        if (CollectionUtils.isNotEmpty(environmentWorkerGroupRelations)) {
            throw new ServiceException(Status.WORKER_GROUP_DEPENDENT_ENVIRONMENT_EXISTS,
                    environmentWorkerGroupRelations.size());
        }
    }

    private void checkWorkerGroupAddrList(String workerGroupAddress) {
        if (Strings.isNullOrEmpty(workerGroupAddress)) {
            return;
        }
        Map<String, String> serverMaps = registryClient.getServerMaps(RegistryNodeType.WORKER);
        for (String addr : workerGroupAddress.split(Constants.COMMA)) {
            if (!serverMaps.containsKey(addr)) {
                throw new ServiceException(Status.WORKER_ADDRESS_INVALID);
            }
        }
    }

    /**
     * query worker group paging

View on GitHub (pinned to 02eac45a1b)

Solutions

List environments bound to this worker group and edit each environment to remove the worker group from its workerGroups field.
Delete the environment-worker-group relation rows (via the Environment UI) if the environments are obsolete.
Retry the worker group deletion once no environments depend on it.

Example fix

// before: delete directly and fail
workerGroupService.deleteWorkerGroupById(loginUser, id);
// after: unbind environments first
List<EnvironmentWorkerGroupRelation> rels = relationMapper.selectList(
    new QueryWrapper<EnvironmentWorkerGroupRelation>()
        .lambda().eq(EnvironmentWorkerGroupRelation::getWorkerGroup, name));
if (rels.isEmpty()) {
    workerGroupService.deleteWorkerGroupById(loginUser, id);
}

Defensive patterns

Strategy: validation

Validate before calling

List<EnvironmentWorkerGroupRelation> rels = relationMapper.selectList(
    new QueryWrapper<EnvironmentWorkerGroupRelation>()
        .lambda().eq(EnvironmentWorkerGroupRelation::getWorkerGroup, groupName));
boolean deletable = rels.isEmpty();

Try / catch

try {
    workerGroupService.deleteWorkerGroupById(loginUser, id);
} catch (ServiceException e) {
    if (e.getCode() == 1401002) { /* unbind environments first */ }
    else throw e;
}

Prevention

Before deleting a worker group, list environments that reference it in the Environment management page.
Adopt an offboarding checklist: unbind environments -> confirm no running instances -> delete group.
Prefer renaming/retiring groups over hard delete when environments still need them.

When it happens

Trigger: Calling DELETE /worker-groups/{id} (deleteWorkerGroupById) when environmentWorkerGroupRelationMapper.selectList on workerGroup.getName() returns a non-empty list, i.e. at least one environment declares this worker group name.

Common situations: Admin tries to remove a worker group that was selected when configuring one or more environments in the Security > Environment management page; leftover environments after renaming or consolidating worker groups.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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