TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to initialize Cluster: the Cluster is already…

Error message

Failed to initialize Cluster: the Cluster is already initialized.

What it means

Thrown by ClusterManager.InitializeCluster when the ClusterInitialized property is already true, meaning a cluster config (clusterDomain + clusterNodes) already exists on this node. InitializeCluster is a one-time bootstrap; calling it again would orphan the existing cluster zone, catalog zone, and node topology, so it is rejected up front before any state is touched.

Solutions

1. Check ClusterInitialized before calling InitializeCluster and skip or guide the admin to 'add node' instead.
2. To re-initialize, first delete/leave the existing cluster and clear the cluster config.
3. Hide the initialize action in the UI once a cluster is present.

Example fix

// before
clusterManager.InitializeCluster(domain, ips, session);

// after
if (!clusterManager.ClusterInitialized)
    clusterManager.InitializeCluster(domain, ips, session);

if (clusterManager.ClusterInitialized)
    return Conflict("Cluster is already initialized; use 'add node' instead.");
clusterManager.InitializeCluster(domain, ips, session);

static bool CanInitializeCluster(ClusterManager cm) => !cm.ClusterInitialized;

When it happens

Trigger: Invoking InitializeCluster a second time on a node that has already been clustered — e.g. an admin retries the setup wizard, or automation calls the cluster-init API on an already-initialized node.

Common situations: Re-running a provisioning script idempotently without checking cluster state; the UI does not hide the 'initialize cluster' button once a cluster exists; an aborted first attempt that actually completed.

Related errors

• Failed to initialize Cluster: a SSO user cannot initialize…
• Failed to initialize Cluster: failed to create the Cluster…
• DNS Server Cluster config file format is invalid.
• DNS Server Cluster config version not supported.
• Failed to initialize Cluster: the zone

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

Appendix: source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:523

            //finalize
            if (_dnsWebService.DnsServer.ServerDomain.EndsWith("." + _clusterDomain, StringComparison.OrdinalIgnoreCase))
                _dnsWebService.DnsServer.ServerDomain = _dnsWebService.DnsServer.ServerDomain.Substring(0, _dnsWebService.DnsServer.ServerDomain.Length - (_clusterDomain.Length + 1));

            //save all changes
            _dnsWebService.DnsServer.SaveConfigFile();
            _dnsWebService.AuthManager.SaveConfigFile();

            UnloadAndDeleteConfigFile();
        }

        #endregion

        #region primary node

        public void InitializeCluster(string clusterDomain, IReadOnlyList<IPAddress> primaryNodeIpAddresses, UserSession session)
        {
            if (ClusterInitialized)
                throw new DnsServerException("Failed to initialize Cluster: the Cluster is already initialized.");

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

            if (session.User.IsSsoUser)
                throw new DnsServerException("Failed to initialize Cluster: a SSO user cannot initialize cluster. Please login with a local administrator user account and try again.");

            clusterDomain = clusterDomain.ToLowerInvariant();

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

View on GitHub (pinned to d0484b6c1e)