TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to join Cluster: the domain name '{primaryNodeUrl.Hos

Error message

Failed to join Cluster: the domain name '{primaryNodeUrl.Host}' does not have an A/AAAA record configured.

What it means

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.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:1342

        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)
        {
            if (ClusterInitialized)
                throw new DnsServerException("Failed to join Cluster: the Cluster is already initialized.");

            if (!_dnsWebService.IsWebServiceTlsEnabled)
                throw new InvalidOperationException();

            if (IPAddress.TryParse(primaryNodeUrl.Host, out _))
                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.");

            if (primaryNodeIpAddresses is null)
            {
                try
                {
                    IReadOnlyList<IPAddress> ipAddresses = await DnsClient.ResolveIPAsync(_dnsWebService.DnsServer, primaryNodeUrl.Host, _dnsWebService.DnsServer.IPv6Mode, cancellationToken);
                    if (ipAddresses.Count < 1)
                        throw new DnsServerException($"Failed to join Cluster: the domain name '{primaryNodeUrl.Host}' does not have an A/AAAA record configured.");

                    primaryNodeIpAddresses = ipAddresses;
                }
                catch (Exception ex)
                {
                    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);
                }
            }

            //login to primary node API
            using HttpApiClient primaryNodeApiClient = new HttpApiClient(primaryNodeUrl, _dnsWebService.DnsServer.Proxy, _dnsWebService.DnsServer.IPv6Mode, ignoreCertificateErrors, new InternalDnsClient(_dnsWebService.DnsServer, primaryNodeIpAddresses));

            try
            {
                _ = await primaryNodeApiClient.LoginAsync(primaryNodeUsername, primaryNodePassword, primaryNodeTotp, false, cancellationToken);
            }
            catch (TwoFactorAuthRequiredHttpApiClientException ex)
            {

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Publish an A and/or AAAA record for the Primary's domain
2. Pass primaryNodeIpAddresses explicitly to bypass DNS resolution
3. Flush negative caches / wait for TTL

Example fix

// before
await clusterManager.InitializeAndJoinClusterAsync(null, primaryUrl, user, pass);

// after
await clusterManager.InitializeAndJoinClusterAsync(
    secondaryNodeIpAddresses, primaryUrl, user, pass,
    primaryNodeIpAddresses: new[] { IPAddress.Parse("10.0.0.5") }); // bypass DNS

var addrs = await DnsClient.ResolveIPAsync(dnsServer, primaryUrl.Host, dnsServer.IPv6Mode, ct);
if (addrs.Count < 1)
    return BadRequest("Primary host has no A/AAAA record; pass IP manually.");
await clusterManager.InitializeAndJoinClusterAsync(ips, primaryUrl, user, pass, primaryNodeIpAddresses: addrs);

catch (DnsServerException ex) when (ex.Message.Contains("does not have an A/AAAA record"))
{ /* prompt user to enter Primary IP manually */ }

When it happens

Trigger: The Primary's A/AAAA records were deleted or never created; another record type exists but no address record; a stale negative cache.

Common situations: DNS misconfiguration; a zone transfer gap leaving the Primary without A records on the resolver used; a recently changed IP not yet published.

Related errors

• Failed to join Cluster: the Primary node domain name '{prima
• Failed to join Cluster: the Primary Node URL must use the do
• Failed to join Cluster: the Primary node does not have a Clu
• Failed to join Cluster: the zone '{clusterCatalogDomain}' al
• Failed to join Cluster: the zone '{primaryNodeClusterInfo.Cl

AI-assisted analysis of TechnitiumSoftware/DnsServer@d0484b6c1e (2026-08-13). Data as JSON: /api/errors/049ca4584a1e08fe. Report an issue: GitHub.