apache/dolphinscheduler · critical · ServiceException

no master server available

Error message

no master server available

What it means

Thrown by RepeatRunningWorkflowInstanceExecutorDelegate.execute when the registry returns no available master server. The API module needs a live master to send the WorkflowInstanceRepeatRunningRequest to, and without one the repeat-running operation cannot be dispatched.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/RepeatRunningWorkflowInstanceExecutorDelegate.java:53

public class RepeatRunningWorkflowInstanceExecutorDelegate
        implements
            IExecutorDelegate<RepeatRunningWorkflowInstanceExecutorDelegate.RepeatRunningWorkflowInstanceOperation, Void> {

    @Autowired
    private RegistryClient registryClient;

    @Override
    public Void execute(RepeatRunningWorkflowInstanceOperation workflowInstanceControlRequest) {
        final WorkflowInstance workflowInstance = workflowInstanceControlRequest.workflowInstance;
        if (workflowInstance.getState() == null || !workflowInstance.getState().isFinalState()) {
            throw new ServiceException(
                    String.format("The workflow instance: %s status is %s, cannot repeat running",
                            workflowInstance.getName(), workflowInstance.getState()));
        }

        final Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);
        if (masterServer == null) {
            throw new ServiceException("no master server available");
        }
        final WorkflowInstanceRepeatRunningRequest repeatRunningRequest = WorkflowInstanceRepeatRunningRequest.builder()
                .workflowInstanceId(workflowInstance.getId())
                .userId(workflowInstanceControlRequest.executeUser.getId())
                .build();

        final WorkflowInstanceRepeatRunningResponse repeatRunningResponse = Clients
                .withService(IWorkflowControlClient.class)
                .withHost(masterServer.getHost() + ":" + masterServer.getPort())
                .repeatTriggerWorkflowInstance(repeatRunningRequest);
        if (!repeatRunningResponse.isSuccess()) {
            throw new ServiceException(
                    "Repeat running workflow instance failed: " + repeatRunningResponse.getMessage());
        }

        return null;
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Start at least one DolphinScheduler master server and verify it registers in the registry
  2. Check registry (ZooKeeper) connectivity from both master and API servers
  3. Verify masters and API use the same registry namespace/cluster name
  4. Check master logs for startup/registration failures and fix them

Example fix

// before
Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);
if (masterServer == null) { throw new ServiceException("no master server available"); }
// after
// operational fix: ensure master is up
// bin/start.sh -m master-server; verify via zkCli ls /dolphinscheduler/nodes/master
Defensive patterns

Strategy: retry

Validate before calling

List<Server> masters = registryClient.getServerList(RegistryNodeType.MASTER);
if (masters.isEmpty()) { throw new IllegalStateException("No masters registered; start master server"); }

Try / catch

try {
    delegate.execute(op);
} catch (ServiceException e) {
    if ("no master server available".equals(e.getMessage())) {
        // alert ops, retry with backoff after masters register
        retryWithBackoff(op, 3);
    }
}

Prevention

When it happens

Trigger: registryClient.getRandomServer(RegistryNodeType.MASTER) returns empty — no master is registered in ZooKeeper/registry, e.g. no masters started or all masters lost registration.

Common situations: Master service not started before using the API; all masters crashed or were killed; network/registry (ZooKeeper) connectivity problems so masters are unregistered; cluster misconfiguration where the API server points at a different registry namespace than the masters.

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/c140a44b81f2ebc7. Report an issue: GitHub.