apache/dolphinscheduler · error · MasterTaskExecuteException

Pause SubWorkflow: ${name} failed

Error message

Pause SubWorkflow: ${name} failed

What it means

SubWorkflowControlClient.pauseWorkflowInstance calls the sub-workflow's host master via IWorkflowControlClient; any exception during the remote pause (network failure, host down, instance not found, RPC error) is wrapped in a MasterTaskExecuteException with this message.

Source

Thrown at dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/executor/plugin/subworkflow/SubWorkflowControlClient.java:87

    public WorkflowInstanceRecoverSuspendTasksResponse triggerFromSuspendTasks(
                                                                               final WorkflowInstanceRecoverSuspendTasksRequest recoverSuspendTasksRequest) {
        return workflowInstanceRecoverSuspendTaskTrigger.triggerWorkflow(recoverSuspendTasksRequest);
    }

    public WorkflowInstancePauseResponse pauseWorkflowInstance(
                                                               final WorkflowInstancePauseRequest workflowInstancePauseRequest) throws MasterTaskExecuteException {
        final Integer subWorkflowInstanceId = workflowInstancePauseRequest.getWorkflowInstanceId();
        final WorkflowInstance subWorkflowInstance = workflowInstanceDao.queryById(subWorkflowInstanceId);
        if (subWorkflowInstance.getState() != WorkflowExecutionStatus.RUNNING_EXECUTION) {
            return WorkflowInstancePauseResponse.fail("SubWorkflow instance is not running, cannot pause");
        }
        try {
            return Clients
                    .withService(IWorkflowControlClient.class)
                    .withHost(subWorkflowInstance.getHost())
                    .pauseWorkflowInstance(new WorkflowInstancePauseRequest(subWorkflowInstanceId));
        } catch (Exception e) {
            throw new MasterTaskExecuteException("Pause SubWorkflow: " + subWorkflowInstance.getName() + " failed", e);
        }
    }

    public WorkflowInstanceStopResponse stopWorkflowInstance(
                                                             final WorkflowInstanceStopRequest workflowInstanceStopRequest) throws MasterTaskExecuteException {
        final Integer subWorkflowInstanceId = workflowInstanceStopRequest.getWorkflowInstanceId();
        final WorkflowInstance subWorkflowInstance = workflowInstanceDao.queryById(subWorkflowInstanceId);
        if (subWorkflowInstance.getState() != WorkflowExecutionStatus.RUNNING_EXECUTION) {
            return WorkflowInstanceStopResponse.fail("SubWorkflow instance is not running, cannot stop");
        }
        try {
            return Clients
                    .withService(IWorkflowControlClient.class)
                    .withHost(subWorkflowInstance.getHost())
                    .stopWorkflowInstance(new WorkflowInstanceStopRequest(subWorkflowInstance.getId()));
        } catch (Exception e) {
            throw new MasterTaskExecuteException("Kill SubWorkflow: " + subWorkflowInstance.getName() + " failed", e);
        }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Check the wrapped cause (e) for the root RPC/network error and verify the sub-workflow host is up
  2. Confirm the sub workflow instance state in the UI/DB — finished instances cannot be paused
  3. Retry the pause of the parent workflow; if failover happened, let the new master resume

Example fix

// before
throw new MasterTaskExecuteException("Pause SubWorkflow: " + name + " failed", e);
// after (operational fix): ensure master registry/network is healthy, then retry pause via the UI
Defensive patterns

Strategy: retry

Validate before calling

// pre-check sub workflow state and host reachability before pause
if (!isHostReachable(subWorkflowInstance.getHost())) {
    throw new MasterTaskExecuteException("Sub workflow host unreachable: " + subWorkflowInstance.getHost());
}

Try / catch

try {
    client.pauseWorkflowInstance(request);
} catch (MasterTaskExecuteException e) {
    log.warn("Pause sub workflow failed, will retry", e);
    retryWithBackoff(3, () -> client.pauseWorkflowInstance(request));
}

Prevention

When it happens

Trigger: The sub-workflow's host master is unreachable/crashed, the sub workflow instance already finished (cannot be paused), or the RPC request times out or returns an error.

Common situations: Master failover while a sub-workflow task is running, network partitions between masters, or users killing the sub-workflow in the UI while the parent tries to pause it.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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