apache/dolphinscheduler · critical · ServiceException

no master server available

Error message

no master server available

What it means

Thrown by TriggerWorkflowExecutorDelegate.execute when the registry has no available master server. Manually triggering a workflow requires dispatching a WorkflowManualTriggerRequest to a master, so with zero registered masters the trigger cannot proceed and this ServiceException is raised before any RPC.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/TriggerWorkflowExecutorDelegate.java:46

import org.apache.dolphinscheduler.registry.api.enums.RegistryNodeType;

import lombok.extern.slf4j.Slf4j;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class TriggerWorkflowExecutorDelegate implements IExecutorDelegate<TriggerWorkflowDTO, Integer> {

    @Autowired
    private RegistryClient registryClient;

    @Override
    public Integer execute(final TriggerWorkflowDTO triggerWorkflowDTO) {
        final Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);
        if (masterServer == null) {
            throw new ServiceException("no master server available");
        }
        final WorkflowManualTriggerResponse workflowManualTriggerResponse = Clients
                .withService(IWorkflowControlClient.class)
                .withHost(masterServer.getHost() + ":" + masterServer.getPort())
                .manualTriggerWorkflow(transform2WorkflowTriggerRequest(triggerWorkflowDTO));
        if (!workflowManualTriggerResponse.isSuccess()) {
            throw new ServiceException("Trigger workflow failed: " + workflowManualTriggerResponse.getMessage());
        }
        return workflowManualTriggerResponse.getWorkflowInstanceId();

    }

    private WorkflowManualTriggerRequest transform2WorkflowTriggerRequest(TriggerWorkflowDTO triggerWorkflowDTO) {
        return WorkflowManualTriggerRequest.builder()
                .userId(triggerWorkflowDTO.getLoginUser().getId())
                .workflowDefinitionCode(triggerWorkflowDTO.getWorkflowDefinition().getCode())
                .workflowDefinitionVersion(triggerWorkflowDTO.getWorkflowDefinition().getVersion())
                .startNodes(triggerWorkflowDTO.getStartNodes())

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Start at least one master server and confirm registration in the registry
  2. Verify ZooKeeper connectivity and that masters renew their sessions
  3. Ensure API server and masters share the same registry namespace configuration
  4. Check master startup logs for registration errors

Example fix

// before
Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);
if (masterServer == null) { throw new ServiceException("no master server available"); }
// after
// operational: bring up master and verify
// zkCli.sh ls /dolphinscheduler/nodes/master  -> expect at least one entry
Defensive patterns

Strategy: retry

Validate before calling

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

Try / catch

try {
    int id = delegate.execute(dto);
} catch (ServiceException e) {
    if ("no master server available".equals(e.getMessage())) {
        retryWithBackoff(dto, 3); // after masters recover
    }
}

Prevention

When it happens

Trigger: registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null) yields null because no master is registered — masters never started, all crashed, or registry (ZooKeeper) session lost.

Common situations: Calling the workflow trigger API before the master tier is up; all masters down after deployment or crash; ZooKeeper outage dropping master registrations; API and masters configured with different registry namespaces.

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