TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to promote to Primary node: the Cluster is not initia

Error message

Failed to promote to Primary node: the Cluster is not initialized.

What it means

Thrown at the top of PromoteToPrimaryNodeAsync when ClusterInitialized is false. Promotion turns the local secondary into the cluster primary, which requires an existing cluster with a current primary to replace; a standalone node has nothing to promote within.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:1940

                UpdateConfigRefreshTimer(_configRefreshIntervalSeconds * 1000); //apply new interval to config refresh timer immediately
                saveConfig = true;
            }

            if (primaryNodeClusterInfo.ConfigRetryIntervalSeconds != _configRetryIntervalSeconds)
            {
                _configRetryIntervalSeconds = primaryNodeClusterInfo.ConfigRetryIntervalSeconds;
                saveConfig = true;
            }

            //save changes
            if (saveConfig)
                SaveConfigFile();
        }

        public async Task PromoteToPrimaryNodeAsync(bool forceDeletePrimary)
        {
            if (!ClusterInitialized)
                throw new DnsServerException("Failed to promote to Primary node: the Cluster is not initialized.");

            //do validation
            ClusterNode selfNewPrimaryNode = GetSelfNode();
            if (selfNewPrimaryNode.Type != ClusterNodeType.Secondary)
                throw new DnsServerException("Failed to promote to Primary node: only Secondary nodes can be promoted to Primary nodes.");

            string clusterCatalogDomain = "cluster-catalog." + _clusterDomain;

            AuthZoneInfo clusterCatalogZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(clusterCatalogDomain);
            if (clusterCatalogZoneInfo is null)
                throw new DnsServerException("Failed to promote to Primary node: the Cluster Secondary Catalog zone does not exist.");

            AuthZoneInfo clusterZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(_clusterDomain);
            if (clusterZoneInfo is null)
                throw new DnsServerException("Failed to promote to Primary node: the Cluster Secondary zone does not exist.");

            //stop cluster config refresh timer
            StopConfigRefreshTimer();

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Guard on ClusterInitialized; report 'not clustered' instead of promoting.
2. If clustering is intended, JoinClusterAsync as a secondary first, then promote.
3. Hide the promote action when the node is not clustered or not a secondary.

Example fix

// before
await clusterManager.PromoteToPrimaryNodeAsync(forceDeletePrimary: false);

// after
if (!clusterManager.ClusterInitialized)
    return BadRequest("Not clustered; cannot promote.");
await clusterManager.PromoteToPrimaryNodeAsync(forceDeletePrimary: false);

if (!clusterManager.ClusterInitialized)
    return BadRequest("Not clustered; cannot promote.");
await clusterManager.PromoteToPrimaryNodeAsync(forceDeletePrimary: false);

static bool CanPromote(ClusterManager cm) => cm.ClusterInitialized;

try { await clusterManager.PromoteToPrimaryNodeAsync(false); }
catch (DnsServerException ex) when (ex.Message.Contains("not initialized"))
{ /* join a cluster first, then promote */ }

When it happens

Trigger: Calling PromoteToPrimaryNodeAsync on a server that is not part of any cluster.

Common situations: Operator clicked 'promote to primary' on a standalone box; the node already left the cluster; cluster config cleared between page load and the action.

Related errors

• Failed to leave Cluster: the Cluster is not initialized.
• Failed to update Primary node: the Cluster is not initialize
• Failed to refresh configuration: the Cluster is not initiali
• Failed to resync configuration: the Cluster is not initializ
• Failed to promote to Primary node: only Secondary nodes can

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