TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to initialize Cluster: the Cluster is already initial

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.

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)

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 c
• Failed to initialize Cluster: failed to create the Cluster z
• Time-based one-time password (TOTP) is already enabled for u
• Time-based one-time password (TOTP) was not initialized for
• Time-based one-time password (TOTP) is already disabled for

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