{"record":{"id":"3ff7e2b68c705a6c","repo":"apache/dolphinscheduler","slug":"no-master-server-available","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/BackfillWorkflowExecutorDelegate.java","lineNumber":168,"sourceCode":"        int start = 0;\n        for (int i = 0; i < numParts; i++) {\n            int currentSize = baseSize;\n            if (i == numParts - 1) {\n                currentSize += remainder;\n            }\n            List<ZonedDateTime> part = dateTimeList.subList(start, start + currentSize);\n            result.add(part);\n            start += currentSize;\n        }\n\n        return result;\n    }\n\n    private Integer doBackfillWorkflow(final BackfillWorkflowDTO backfillWorkflowDTO,\n                                       final List<ZonedDateTime> backfillDateTimes) {\n        final Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);\n        if (masterServer == null) {\n            throw new ServiceException(\"no master server available\");\n        }\n\n        final List<String> backfillTimeList =\n                backfillDateTimes.stream().map(DateUtils::dateToString).collect(Collectors.toList());\n\n        final WorkflowDefinition workflowDefinition = backfillWorkflowDTO.getWorkflowDefinition();\n        final WorkflowBackfillTriggerRequest backfillTriggerRequest = WorkflowBackfillTriggerRequest.builder()\n                .userId(backfillWorkflowDTO.getLoginUser().getId())\n                .backfillTimeList(backfillTimeList)\n                .workflowCode(workflowDefinition.getCode())\n                .workflowVersion(workflowDefinition.getVersion())\n                .startNodes(backfillWorkflowDTO.getStartNodes())\n                .failureStrategy(backfillWorkflowDTO.getFailureStrategy())\n                .taskDependType(backfillWorkflowDTO.getTaskDependType())\n                .warningType(backfillWorkflowDTO.getWarningType())\n                .warningGroupId(backfillWorkflowDTO.getWarningGroupId())\n                .workflowInstancePriority(backfillWorkflowDTO.getWorkflowInstancePriority())\n                .workerGroup(backfillWorkflowDTO.getWorkerGroup())","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/BackfillWorkflowExecutorDelegate.java#L150-L186","documentation":"Thrown by the API layer's backfill delegate when no master server can be found in the registry. Backfilling a workflow requires forwarding the trigger request to a live master node; if the registry reports no master, the API cannot proceed and throws ServiceException before any request is sent.","triggerScenarios":"Calling the workflow backfill API (BackfillWorkflowExecutorDelegate.doBackfillWorkflow) while registryClient.getRandomServer(RegistryNodeType.MASTER) returns empty — i.e. zero registered master nodes in ZooKeeper.","commonSituations":"All master services are down or crashed; masters failed to register with ZooKeeper (wrong registry address in master config); ZooKeeper itself is unreachable so the server list is empty; network partition between API server and masters; masters still starting up during cluster rollout.","solutions":["Start at least one MasterServer and verify it registers in ZooKeeper under the masters node","Check masters' application.yaml registry (ZooKeeper) connect settings match the API server's registry settings","Verify ZooKeeper connectivity from the API host (zkCli / telnet to the quorum)","Check master logs for registration/heartbeat failures and restart failed masters","Re-run the backfill once the cluster shows the master as healthy"],"exampleFix":"// before: blindly calling backfill API with cluster down -> 500 'no master server available'\napiService.backfillWorkflow(...)\n// after: pre-check cluster health before invoking\nif (registryClient.getRandomServer(RegistryNodeType.MASTER).isEmpty()) {\n    throw new IllegalStateException(\"Start a master server before backfilling workflows\");\n}\napiService.backfillWorkflow(...)","handlingStrategy":"validation","validationCode":"boolean masterAvailable = !registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(new Server()).getHost().isEmpty();\nif (!masterAvailable) throw new IllegalStateException(\"No master server registered; cannot backfill\");","typeGuard":"boolean hasMaster(RegistryClient c) { return c.getRandomServer(RegistryNodeType.MASTER).isPresent(); }","tryCatchPattern":"try { delegate.backfill(dto, dates); } catch (ServiceException e) { if (e.getMessage().contains(\"no master server available\")) { alertOpsClusterDown(); } else { throw e; } }","preventionTips":["Monitor ZooKeeper for registered master count and alert when it drops to zero","Run master health checks before submitting workflows in CI/automation","Keep registry endpoints consistent across API and master configs","Set up automatic master restart/failover"],"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"}