TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to join Cluster: the Primary node does not have a Clu

Error message

Failed to join Cluster: the Primary node does not have a Cluster initialized.

What it means

The would-be Secondary contacted the Primary and learned (via GetClusterStateAsync) that the Primary itself has no cluster initialized. You can only join a Primary that already created a cluster.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:1371

            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
                ClusterInfo primaryNodeClusterInfo = await primaryNodeApiClient.GetClusterStateAsync(cancellationToken: cancellationToken);

                //do validations
                if (!primaryNodeClusterInfo.ClusterInitialized)
                    throw new DnsServerException("Failed to join Cluster: the Primary node does not have a Cluster initialized.");

                string clusterCatalogDomain = "cluster-catalog." + primaryNodeClusterInfo.ClusterDomain;

                if (_dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(clusterCatalogDomain) is not null)
                    throw new DnsServerException($"Failed to join Cluster: the zone '{clusterCatalogDomain}' already exists. Please delete the '{clusterCatalogDomain}' zone and try again.");

                if (_dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(primaryNodeClusterInfo.ClusterDomain) is not null)
                    throw new DnsServerException($"Failed to join Cluster: the zone '{primaryNodeClusterInfo.ClusterDomain}' already exists. Please delete the '{primaryNodeClusterInfo.ClusterDomain}' zone and try again.");

                //create self node
                string serverDomain = _dnsWebService.DnsServer.ServerDomain;
                if (!serverDomain.EndsWith("." + primaryNodeClusterInfo.ClusterDomain, StringComparison.OrdinalIgnoreCase))
                {
                    int x = serverDomain.IndexOf('.');
                    if (x < 0)
                        serverDomain = serverDomain + "." + primaryNodeClusterInfo.ClusterDomain;
                    else
                        serverDomain = string.Concat(serverDomain.AsSpan(0, x), ".", primaryNodeClusterInfo.ClusterDomain);

View on GitHub (pinned to d0484b6c1e)

Solutions

Create the cluster on the intended Primary first, then join
Verify the target URL points to the actual cluster Primary
Retry join after Primary initialization completes

Example fix

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

// after
var info = await primaryNodeApiClient.GetClusterStateAsync();
if (!info.ClusterInitialized)
    throw new InvalidOperationException("Primary has no cluster; create it first.");
await clusterManager.InitializeAndJoinClusterAsync(ips, primaryUrl, user, pass);

Defensive patterns

Strategy: validation

Validate before calling

var info = await primaryNodeApiClient.GetClusterStateAsync(ct);
if (!info.ClusterInitialized)
    return BadRequest("Target Primary has no cluster initialized.");
await clusterManager.InitializeAndJoinClusterAsync(ips, primaryUrl, user, pass);

Try / catch

catch (DnsServerException ex) when (ex.Message.Contains("does not have a Cluster initialized"))
{ /* instruct: create cluster on Primary first */ }

Prevention

Verify the Primary's cluster state before attempting join
Document the create-then-join ordering for operators

When it happens

Trigger: Joining a node that is standalone; the operator ran 'join' before 'create cluster' on the intended Primary; pointing at the wrong server.

Common situations: Wrong Primary URL; Primary cluster creation failed or was reverted; targeting a fresh install.

Related errors

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