{"record":{"id":"049ca4584a1e08fe","repo":"TechnitiumSoftware/DnsServer","slug":"failed-to-join-cluster-the-domain-name-primaryn","errorCode":null,"errorMessage":"Failed to join Cluster: the domain name '{primaryNodeUrl.Host}' does not have an A/AAAA record configured.","messagePattern":"Failed to join Cluster: the domain name '(.+?)' does not have an A/AAAA record configured\\.","errorType":"exception","errorClass":"DnsServerException","httpStatus":null,"severity":"error","filePath":"DnsServerCore/Cluster/ClusterManager.cs","lineNumber":1342,"sourceCode":"\n        public async Task InitializeAndJoinClusterAsync(IReadOnlyList<IPAddress> secondaryNodeIpAddresses, Uri primaryNodeUrl, string primaryNodeUsername, string primaryNodePassword, string primaryNodeTotp = null, IReadOnlyList<IPAddress> primaryNodeIpAddresses = null, bool ignoreCertificateErrors = false, CancellationToken cancellationToken = default)\n        {\n            if (ClusterInitialized)\n                throw new DnsServerException(\"Failed to join Cluster: the Cluster is already initialized.\");\n\n            if (!_dnsWebService.IsWebServiceTlsEnabled)\n                throw new InvalidOperationException();\n\n            if (IPAddress.TryParse(primaryNodeUrl.Host, out _))\n                throw new DnsServerException(\"Failed to join Cluster: the Primary Node URL must use the domain name of the Primary node and not its IP address.\");\n\n            if (primaryNodeIpAddresses is null)\n            {\n                try\n                {\n                    IReadOnlyList<IPAddress> ipAddresses = await DnsClient.ResolveIPAsync(_dnsWebService.DnsServer, primaryNodeUrl.Host, _dnsWebService.DnsServer.IPv6Mode, cancellationToken);\n                    if (ipAddresses.Count < 1)\n                        throw new DnsServerException($\"Failed to join Cluster: the domain name '{primaryNodeUrl.Host}' does not have an A/AAAA record configured.\");\n\n                    primaryNodeIpAddresses = ipAddresses;\n                }\n                catch (Exception ex)\n                {\n                    throw new DnsServerException($\"Failed to join Cluster: the Primary node domain name '{primaryNodeUrl.Host}' could not be resolved to an IP address. Please specify the Primary node IP address manually.\", ex);\n                }\n            }\n\n            //login to primary node API\n            using HttpApiClient primaryNodeApiClient = new HttpApiClient(primaryNodeUrl, _dnsWebService.DnsServer.Proxy, _dnsWebService.DnsServer.IPv6Mode, ignoreCertificateErrors, new InternalDnsClient(_dnsWebService.DnsServer, primaryNodeIpAddresses));\n\n            try\n            {\n                _ = await primaryNodeApiClient.LoginAsync(primaryNodeUsername, primaryNodePassword, primaryNodeTotp, false, cancellationToken);\n            }\n            catch (TwoFactorAuthRequiredHttpApiClientException ex)\n            {","sourceCodeStart":1324,"sourceCodeEnd":1360,"githubUrl":"https://github.com/TechnitiumSoftware/DnsServer/blob/d0484b6c1e7439cdc53d67d81e9c876cda2ad756/DnsServerCore/Cluster/ClusterManager.cs#L1324-L1360","documentation":"During join, the Primary's domain name resolved to zero A/AAAA records (DnsClient.ResolveIPAsync returned an empty list). The host exists in DNS but has no address records, so the Secondary cannot reach it.","triggerScenarios":"The Primary's A/AAAA records were deleted or never created; another record type exists but no address record; a stale negative cache.","commonSituations":"DNS misconfiguration; a zone transfer gap leaving the Primary without A records on the resolver used; a recently changed IP not yet published.","solutions":["Publish an A and/or AAAA record for the Primary's domain","Pass primaryNodeIpAddresses explicitly to bypass DNS resolution","Flush negative caches / wait for TTL"],"exampleFix":"// before\nawait clusterManager.InitializeAndJoinClusterAsync(null, primaryUrl, user, pass);\n\n// after\nawait clusterManager.InitializeAndJoinClusterAsync(\n    secondaryNodeIpAddresses, primaryUrl, user, pass,\n    primaryNodeIpAddresses: new[] { IPAddress.Parse(\"10.0.0.5\") }); // bypass DNS","handlingStrategy":"validation","validationCode":"var addrs = await DnsClient.ResolveIPAsync(dnsServer, primaryUrl.Host, dnsServer.IPv6Mode, ct);\nif (addrs.Count < 1)\n    return BadRequest(\"Primary host has no A/AAAA record; pass IP manually.\");\nawait clusterManager.InitializeAndJoinClusterAsync(ips, primaryUrl, user, pass, primaryNodeIpAddresses: addrs);","typeGuard":null,"tryCatchPattern":"catch (DnsServerException ex) when (ex.Message.Contains(\"does not have an A/AAAA record\"))\n{ /* prompt user to enter Primary IP manually */ }","preventionTips":["Ensure the Primary has published A/AAAA records before joining","Allow manual IP entry as a fallback in the join form"],"tags":["cluster","network","dns-resolution","join","dns-server"],"backgroundTag":null,"analyzedSha":"d0484b6c1e7439cdc53d67d81e9c876cda2ad756","analyzedAt":"2026-08-13T22:57:35.508Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}