apache/dolphinscheduler · error · ServiceException

DELETE_ENVIRONMENT_RELATED_TASK_EXISTS

DELETE_ENVIRONMENT_RELATED_TASK_EXISTS

Error message

Status.DELETE_ENVIRONMENT_RELATED_TASK_EXISTS

What it means

Thrown by EnvironmentServiceImpl.deleteEnvironmentByCode when task definitions still reference the environment (taskDefinitionDao.countByEnvironmentCode > 0). Environments in use by tasks cannot be deleted to avoid breaking workflow execution. The event is logged with the related task count and code before throwing.

Source

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

    /**
     * delete environment
     *
     * @param loginUser login user
     * @param code environment code
     */
    @Transactional
    @Override
    public void deleteEnvironmentByCode(User loginUser, Long code) {
        if (!canOperatorPermissions(loginUser, null, AuthorizationType.ENVIRONMENT, ENVIRONMENT_DELETE)) {
            throw new ServiceException(Status.USER_NO_OPERATION_PERM);
        }

        long relatedTaskNumber = taskDefinitionDao.countByEnvironmentCode(code);

        if (relatedTaskNumber > 0) {
            log.warn("Delete environment failed because {} tasks is using it, environmentCode:{}.",
                    relatedTaskNumber, code);
            throw new ServiceException(Status.DELETE_ENVIRONMENT_RELATED_TASK_EXISTS);
        }

        int delete = environmentMapper.deleteByCode(code);
        if (delete <= 0) {
            log.error("Environment delete error, environmentCode:{}.", code);
            throw new ServiceException(Status.DELETE_ENVIRONMENT_ERROR);
        }
        relationMapper.delete(new QueryWrapper<EnvironmentWorkerGroupRelation>()
                .lambda()
                .eq(EnvironmentWorkerGroupRelation::getEnvironmentCode, code));
        log.info("Environment and relations delete complete, environmentCode:{}.", code);
    }

    /**
     * update environment
     *
     * @param loginUser login user
     * @param code environment code

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Find task definitions using the environment (query task definitions with that environment code) and reassign or clear their environment setting, then retry the delete.
2. Delete or update the referencing task definitions first (via UI or task-definition update API), then delete the environment.
3. If the environment should stay, skip the delete and keep it — this error is protective.

Example fix

// before
environmentService.deleteEnvironmentByCode(loginUser, code); // throws if in use
// after
long inUse = taskDefinitionDao.countByEnvironmentCode(code);
if (inUse > 0) {
    taskDefinitions.forEach(td -> td.setEnvironmentCode(null)); // reassign/clear first
}
environmentService.deleteEnvironmentByCode(loginUser, code);

public boolean environmentInUse(long code) {
    return taskDefinitionDao.countByEnvironmentCode(code) > 0;
}
// Only call delete when environmentInUse(code) == false

try {
    environmentService.deleteEnvironmentByCode(loginUser, code);
} catch (ServiceException e) {
    if (String.valueOf(e.getMessage()).contains("DELETE_ENVIRONMENT_RELATED_TASK_EXISTS")) {
        // reassign or clear environment on the referencing task definitions first
    }
}

When it happens

Trigger: DELETE /dolphinscheduler/environments/{code} where one or more rows in t_ds_task_definition have environment_code equal to the target code; deleting an environment that tasks were configured to run with.

Common situations: Cleanup scripts removing 'unused' environments that are in fact referenced by dormant task definitions; environments referenced by tasks imported from another cluster; users unaware that task definitions keep environment_code even when a workflow is not running.

Related errors

• 120034
• 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/193406de84f64bea. Report an issue: GitHub.