TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to join Cluster: the Cluster is already initialized.

Error message

Failed to join Cluster: the Cluster is already initialized.

What it means

InitializeAndJoinClusterAsync refuses because this node already belongs to a cluster (ClusterInitialized is true). A node can join only once; to rejoin it must leave or reset first.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:1328

            }
            catch (Exception ex)
            {
                _dnsWebService.LogManager.Write(ex);
            }
            finally
            {
                _notifyAllSecondaryNodesTimerTriggered = false;
            }
        }

        #endregion

        #region secondary node

        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)

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Leave the current cluster / reset cluster state before joining again
2. If already a Secondary of the desired cluster, no action is needed
3. Check ClusterInitialized before attempting join

Example fix

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

// after
if (clusterManager.ClusterInitialized)
    await clusterManager.LeaveClusterAsync(); // or prompt user
await clusterManager.InitializeAndJoinClusterAsync(ips, primaryUrl, user, pass);

if (clusterManager.ClusterInitialized)
    return Conflict("Node is already part of a cluster; leave first.");
await clusterManager.InitializeAndJoinClusterAsync(ips, primaryUrl, user, pass);

catch (DnsServerException ex) when (ex.Message.Contains("already initialized"))
{ /* offer to leave current cluster and retry */ }

When it happens

Trigger: Calling join on a node that is already a Primary or Secondary; double-clicking 'join cluster'; retrying join after a partial success.

Common situations: Operator forgetting the node is already clustered; automation re-running join idempotently without checking; a recovered node that still has cluster state.

Related errors

• Failed to update Secondary node: the Cluster is not initiali
• Failed to transfer configuration: the Cluster is not initial
• Failed to update Cluster options: the Cluster is not initial
• Failed to join Cluster: the Primary node does not have a Clu
• Failed to join Cluster: the zone '{clusterCatalogDomain}' al

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