TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to join Cluster: the Primary node domain name '{prima

Error message

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.

What it means

During join, resolving the Primary's domain name threw an exception (the DNS lookup failed entirely). The wrapper re-throws with a hint to supply the IP manually via primaryNodeIpAddresses.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:1348

            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)
            {
                throw new TwoFactorAuthRequiredWebServiceException("Failed to join Cluster: two-factor authentication is required by the Primary node user account.", ex);
            }

            try
            {
                //get cluster info

View on GitHub (pinned to d0484b6c1e)

Solutions

  1. Pass primaryNodeIpAddresses explicitly to skip resolution
  2. Fix the joining node's DNS/upstream resolver and network
  3. Verify the Primary hostname exists in a resolvable zone

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") });
Defensive patterns

Strategy: fallback

Validate before calling

IReadOnlyList<IPAddress> primaryIps;
try { primaryIps = await DnsClient.ResolveIPAsync(dnsServer, primaryUrl.Host, dnsServer.IPv6Mode, ct); }
catch { primaryIps = userProvidedPrimaryIps; }
if (primaryIps is null || primaryIps.Count == 0)
    return BadRequest("Cannot resolve Primary; provide its IP manually.");
await clusterManager.InitializeAndJoinClusterAsync(ips, primaryUrl, user, pass, primaryNodeIpAddresses: primaryIps);

Try / catch

catch (DnsServerException ex) when (ex.Message.Contains("could not be resolved"))
{ /* fall back to user-supplied Primary IP and retry join */ }

Prevention

When it happens

Trigger: Resolver unreachable; NXDOMAIN for the Primary host; SERVFAIL; a network or DNS outage on the joining node; the configured upstream resolver cannot answer.

Common situations: The joining node has no working DNS path to resolve the Primary; a firewall blocking DNS; a misconfigured upstream resolver; a transient DNS failure.

Related errors

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