apache/dolphinscheduler · error · WorkerGroupNotFoundException

WorkerGroupNotFoundException(workerGroup)

Error message

WorkerGroupNotFoundException(workerGroup)

What it means

The master could not find the worker group named in the task's context among the worker clusters currently known from the registry, so PhysicalTaskExecutorClientDelegator.dispatch throws WorkerGroupNotFoundException before any worker is selected. This is a configuration/discovery mismatch: the task references a group that has no registered workers.

Source

Thrown at dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/task/client/PhysicalTaskExecutorClientDelegator.java:72

    @Autowired
    private MasterConfig masterConfig;

    @Autowired
    private IWorkerLoadBalancer workerLoadBalancer;

    @Autowired
    private ClusterManager clusterManager;

    @Override
    public void dispatch(final ITaskExecution taskExecution) throws TaskDispatchException {
        final TaskExecutionContext taskExecutionContext = taskExecution.getTaskExecutionContext();
        final String taskName = taskExecutionContext.getTaskName();
        final String workerGroup = taskExecutionContext.getWorkerGroup();

        // workerGroup not exist
        if (!clusterManager.getWorkerClusters().containsWorkerGroup(workerGroup)) {
            throw new WorkerGroupNotFoundException(workerGroup);
        }

        // select an available worker from the worker group; throws NoAvailableWorkerException if none is available.
        final String physicalTaskExecutorAddress = workerLoadBalancer
                .select(workerGroup)
                .map(Host::of)
                .map(Host::getAddress)
                .orElseThrow(() -> new NoAvailableWorkerException(workerGroup));

        taskExecutionContext.setHost(physicalTaskExecutorAddress);
        taskExecution.getTaskInstance().setHost(physicalTaskExecutorAddress);

        try {
            final TaskExecutorDispatchResponse taskExecutorDispatchResponse = Clients
                    .withService(IPhysicalTaskExecutorOperator.class)
                    .withHost(physicalTaskExecutorAddress)
                    .dispatchTask(TaskExecutorDispatchRequest.of(taskExecution.getTaskExecutionContext()));
            if (!taskExecutorDispatchResponse.isDispatchSuccess()) {

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Correct the task's worker group name in the workflow definition to match a group that actually has registered workers
  2. Verify workers belonging to that group are up and registered in the registry (check worker config: worker.group) and wait for registration before running
  3. Check ClusterManager/registry state (UI -> service management) to list existing worker groups and pick a valid one
  4. If the group is intentional, deploy/configure at least one worker with that group name

Example fix

// before (task definition yaml)
workerGroup: prod_gpu_pool   // no such group registered
// after
workerGroup: default         // or a group with live workers
Defensive patterns

Strategy: validation

Validate before calling

// before running the workflow
String workerGroup = taskExecutionContext.getWorkerGroup();
if (!clusterManager.getWorkerClusters().containsWorkerGroup(workerGroup)) {
    throw new WorkerGroupNotFoundException(workerGroup);
}

Try / catch

try {
    taskExecutorClient.dispatch(taskExecution);
} catch (WorkerGroupNotFoundException e) {
    log.error("Worker group '{}' does not exist; fix the task definition or register workers", e.getWorkerGroup());
}

Prevention

When it happens

Trigger: clusterManager.getWorkerClusters().containsWorkerGroup(workerGroup) returns false during dispatch — the taskExecutionContext.getWorkerGroup() value does not match any worker group registered in the registry.

Common situations: Typo or renamed worker group in the task/workflow definition; worker group defined only in the UI tenant/env config but no worker ever configured with that group; workers down or not yet registered so the group vanished from the registry; environment moved from dev to prod with different group names.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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