{"record":{"id":"21261101f24c33ad","repo":"apache/dolphinscheduler","slug":"no-master-server-available-212611","errorCode":null,"errorMessage":"no master server available","messagePattern":"no master server available","errorType":"exception","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/RecoverSuspendedWorkflowInstanceExecutorDelegate.java","lineNumber":52,"sourceCode":"@Component\npublic class RecoverSuspendedWorkflowInstanceExecutorDelegate\n        implements\n            IExecutorDelegate<RecoverSuspendedWorkflowInstanceExecutorDelegate.RecoverSuspendedWorkflowInstanceOperation, Void> {\n\n    @Autowired\n    private RegistryClient registryClient;\n\n    @Override\n    public Void execute(RecoverSuspendedWorkflowInstanceOperation workflowInstanceControlRequest) {\n        final WorkflowInstance workflowInstance = workflowInstanceControlRequest.workflowInstance;\n        if (!workflowInstance.getState().isPaused() && !workflowInstance.getState().isStopped()) {\n            throw new ServiceException(\n                    String.format(\"The workflow instance: %s state is %s, cannot recovery\", workflowInstance.getName(),\n                            workflowInstance.getState()));\n        }\n        final Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);\n        if (masterServer == null) {\n            throw new ServiceException(\"no master server available\");\n        }\n        final WorkflowInstanceRecoverSuspendTasksRequest recoverSuspendTaskRequest =\n                WorkflowInstanceRecoverSuspendTasksRequest.builder()\n                        .workflowInstanceId(workflowInstance.getId())\n                        .userId(workflowInstanceControlRequest.executeUser.getId())\n                        .build();\n\n        final WorkflowInstanceRecoverSuspendTasksResponse recoverSuspendTaskResponse = Clients\n                .withService(IWorkflowControlClient.class)\n                .withHost(masterServer.getHost() + \":\" + masterServer.getPort())\n                .triggerFromSuspendTasks(recoverSuspendTaskRequest);\n        if (!recoverSuspendTaskResponse.isSuccess()) {\n            throw new ServiceException(\"Recover workflow instance failed: \" + recoverSuspendTaskResponse.getMessage());\n        }\n        return null;\n    }\n\n    public static class RecoverSuspendedWorkflowInstanceOperation {","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/RecoverSuspendedWorkflowInstanceExecutorDelegate.java#L34-L70","documentation":"Thrown when the API cannot find a master server in the registry while attempting to recover a suspended workflow instance. The recovery request must be sent to a master; an empty master list aborts the operation.","triggerScenarios":"RecoverSuspendedWorkflowInstanceExecutorDelegate.execute calls registryClient.getRandomServer(RegistryNodeType.MASTER) after the state check and gets an empty result — no masters registered.","commonSituations":"All masters stopped for maintenance while users attempt recoveries; ZooKeeper connectivity problems hiding healthy masters; master registration failures after a config change; partial cluster startup.","solutions":["Ensure at least one MasterServer is running and registered in ZooKeeper","Align registry configuration between masters, workers, and the API server","Check ZooKeeper availability and network paths; restart failed masters","Retry the recover operation once the master list is populated"],"exampleFix":"// before\napi.recoverSuspendedWorkflowInstance(instanceId, userId);\n// after\nif (registryClient.getRandomServer(RegistryNodeType.MASTER).isPresent()) {\n    api.recoverSuspendedWorkflowInstance(instanceId, userId);\n} else {\n    throw new IllegalStateException(\"Cluster has no active master server\");\n}","handlingStrategy":"validation","validationCode":"boolean masterAvailable = registryClient.getRandomServer(RegistryNodeType.MASTER).isPresent();\nif (!masterAvailable) throw new IllegalStateException(\"No master registered; cannot recover suspended instance\");","typeGuard":"boolean hasMaster(RegistryClient c) { return c.getRandomServer(RegistryNodeType.MASTER).isPresent(); }","tryCatchPattern":"try { delegate.recoverSuspended(op); } catch (ServiceException e) { if (e.getMessage().contains(\"no master server available\")) { waitForMasterAndRetry(op); } else { throw e; } }","preventionTips":["Monitor and alert on registered master count","Cluster health-check before issuing recovery requests","Keep registry configuration consistent across all components","Automate master restart on registration loss"],"tags":["dolphinscheduler","master-unavailable","registry","cluster-health"],"backgroundTag":"connection-refused","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}