apache/dolphinscheduler · error · ServiceException

WorkflowInstance: %s stop failed

Error message

WorkflowInstance: %s stop failed

What it means

Wrapping variant of the stop failure thrown by StopWorkflowInstanceExecutorDelegate.stopInMaster: any non-ServiceException exception during the RPC to the master (connection refused, timeout, host unreachable) is wrapped in a ServiceException with this message and the original exception as the cause. It means the stop request could not be completed due to a transport/communication problem rather than an explicit master rejection.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/StopWorkflowInstanceExecutorDelegate.java:107

    }

    void stopInMaster(WorkflowInstance workflowInstance) {
        try {
            final WorkflowInstanceStopResponse stopResponse = Clients
                    .withService(IWorkflowControlClient.class)
                    .withHost(workflowInstance.getHost())
                    .stopWorkflowInstance(new WorkflowInstanceStopRequest(workflowInstance.getId()));

            if (stopResponse != null && stopResponse.isSuccess()) {
                log.info("WorkflowInstance: {} stop success", workflowInstance.getName());
            } else {
                throw new ServiceException(
                        "WorkflowInstance: " + workflowInstance.getName() + " stop failed: " + stopResponse);
            }
        } catch (ServiceException e) {
            throw e;
        } catch (Exception e) {
            throw new ServiceException(
                    String.format("WorkflowInstance: %s stop failed", workflowInstance.getName()), e);
        }
    }

    public static class StopWorkflowInstanceOperation {

        private final StopWorkflowInstanceExecutorDelegate stopWorkflowInstanceExecutorDelegate;

        private WorkflowInstance workflowInstance;

        private User executeUser;

        public StopWorkflowInstanceOperation(StopWorkflowInstanceExecutorDelegate stopWorkflowInstanceExecutorDelegate) {
            this.stopWorkflowInstanceExecutorDelegate = stopWorkflowInstanceExecutorDelegate;
        }

        public StopWorkflowInstanceExecutorDelegate.StopWorkflowInstanceOperation onWorkflowInstance(WorkflowInstance workflowInstance) {
            this.workflowInstance = workflowInstance;

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Check connectivity to workflowInstance.getHost() (ping/port) and confirm the master process is running
  2. Inspect the wrapped cause exception for the transport-level error
  3. Wait for master failover and retry the stop against the new host
  4. Verify master advertise address/port configuration matches the registry entry
  5. Check master logs and system resource usage if timeouts recur

Example fix

// before
stopInMaster(instance); // throws wrapped ServiceException on connection failure
// after
try {
    stopInMaster(instance);
} catch (ServiceException e) {
    log.error("Stop failed for {}: {}", instance.getName(), e.getCause(), e);
    // check master health / retry or force-fail in DB
}
Defensive patterns

Strategy: try-catch

Validate before calling

try (Socket s = new Socket()) {
    String[] hp = instance.getHost().split(":");
    s.connect(new InetSocketAddress(hp[0], Integer.parseInt(hp[1])), 2000); // throws if unreachable
}

Try / catch

try {
    delegate.execute(op);
} catch (ServiceException e) {
    Throwable cause = e.getCause();
    log.error("Stop transport failure: {}", cause == null ? e : cause.getMessage(), e);
    // connectivity check, then retry or failover
}

Prevention

When it happens

Trigger: Any Exception thrown while calling stopWorkflowInstance on workflowInstance.getHost(): connection refused (master down), RPC timeout, DNS/hostname resolution failure, serialization errors.

Common situations: Master process killed or crashed so the recorded host is unreachable; network partition between API and master; wrong host registered due to misconfigured advertise address; slow master causing RPC timeouts during heavy load.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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