apache/dolphinscheduler · error · ServiceException

WorkflowInstance: %s pause failed

Error message

WorkflowInstance: %s pause failed

What it means

Wrapper exception for unexpected failures during the pause RPC itself. While calling pauseWorkflowInstance on the master, any non-ServiceException exception (network errors, timeouts, deserialization problems) is caught and rethrown as a ServiceException with this message and the original cause attached.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/PauseWorkflowInstanceExecutorDelegate.java:106

    }

    private void pauseInMaster(WorkflowInstance workflowInstance) {
        try {
            final WorkflowInstancePauseResponse pauseResponse = Clients
                    .withService(IWorkflowControlClient.class)
                    .withHost(workflowInstance.getHost())
                    .pauseWorkflowInstance(new WorkflowInstancePauseRequest(workflowInstance.getId()));

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

    public static class PauseWorkflowInstanceOperation {

        private final PauseWorkflowInstanceExecutorDelegate pauseWorkflowInstanceExecutorDelegate;

        private WorkflowInstance workflowInstance;

        private User executeUser;

        public PauseWorkflowInstanceOperation(PauseWorkflowInstanceExecutorDelegate pauseWorkflowInstanceExecutorDelegate) {
            this.pauseWorkflowInstanceExecutorDelegate = pauseWorkflowInstanceExecutorDelegate;
        }

        public PauseWorkflowInstanceExecutorDelegate.PauseWorkflowInstanceOperation onWorkflowInstance(WorkflowInstance workflowInstance) {
            this.workflowInstance = workflowInstance;

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Inspect the chained cause (getCause()) to identify the underlying network/RPC error
2. Verify the master host is reachable from the API server (ping/telnet host:port)
3. Restart or recover the failed master and retry the pause
4. Increase RPC timeouts if the master is under heavy load

Example fix

// before: no cause inspection, blind retry
try { api.pauseWorkflowInstance(id); } catch (ServiceException e) { retry(id); }
// after: log root cause before retry
try { api.pauseWorkflowInstance(id); }
catch (ServiceException e) {
    log.error("Pause failed, cause: {}", e.getCause(), e);
    retry(id); // only after master confirmed healthy
}

// pre-check master reachability
boolean reachable = ping(instance.getHost(), masterRpcPort);

try { delegate.pause(op); } catch (ServiceException e) { Throwable cause = e.getCause(); if (cause instanceof java.net.ConnectException || cause instanceof java.net.SocketTimeoutException) { retryWithBackoff(op); } else { throw e; } }

When it happens

Trigger: pauseInMaster's RPC to the instance host throws — e.g. connection refused (master down), socket timeout, unknown host, or response unmarshalling failure.

Common situations: Master crashed or restarted between state check and pause call; network partition or firewall blocking API→master port; DNS/hostname resolution issues; master overloaded causing RPC timeout.

Related errors

• WorkflowInstance: %s pause failed: %s
• The workflow instance: %s status is %s, can not pause
• "Pause task: " + taskExecution.getName() + " from executor f
• no master server available
• Backfill workflow failed: %s

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