TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to promote to Primary node: the Cluster Secondary zon

Error message

Failed to promote to Primary node: the Cluster Secondary zone does not exist.

What it means

Thrown by PromoteToPrimaryNodeAsync when GetAuthZoneInfo(_clusterDomain) (the cluster's main secondary zone, distinct from the catalog zone) returns null. Promotion later converts this secondary zone into the cluster's primary zone, so it must pre-exist; absence indicates inconsistent cluster zone state.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:1955

        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();

            //resync config and delete current primary node from the cluster immediately
            ClusterNode existingPrimaryNode = GetPrimaryNode();

            if (!forceDeletePrimary)
            {
                //resync complete config from current primary node to ensure all data is synced
                _configLastSynced = DateTime.UnixEpoch; //to ensure complete config resync
                await existingPrimaryNode.SyncConfigAsync();

                //delete current cluster primary node
                await existingPrimaryNode.DeleteClusterAsync(true);
            }

            //dispose primary node immediately to stop heartbeat

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Re-establish the cluster zone by leaving (force) and rejoining to rebuild secondary zone state.
2. Restore the cluster zone file from backup.
3. Confirm _clusterDomain matches the actual zone name on disk.

Example fix

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

// after
if (dnsServer.AuthZoneManager.GetAuthZoneInfo(clusterManager.ClusterDomain) is null)
{
    await clusterManager.LeaveClusterAsync(force: true);
    await clusterManager.JoinClusterAsync(primaryUrl, creds, ct);
}
await clusterManager.PromoteToPrimaryNodeAsync(forceDeletePrimary: false);

if (dnsServer.AuthZoneManager.GetAuthZoneInfo(clusterManager.ClusterDomain) is null)
    throw new InvalidOperationException($"Missing cluster zone '{clusterManager.ClusterDomain}'; rebuild cluster.");
await clusterManager.PromoteToPrimaryNodeAsync(forceDeletePrimary: false);

static bool ClusterZoneExists(DnsWebService svc, string clusterDomain)
    => svc.DnsServer.AuthZoneManager.GetAuthZoneInfo(clusterDomain) is not null;

try { await clusterManager.PromoteToPrimaryNodeAsync(false); }
catch (DnsServerException ex) when (ex.Message.Contains("Cluster Secondary zone does not exist"))
{
    await clusterManager.LeaveClusterAsync(force: true);
    await clusterManager.JoinClusterAsync(primaryUrl, creds, ct);
}

When it happens

Trigger: Promoting a secondary whose main '<clusterDomain>' secondary zone is missing (deleted/renamed/never created), even though the catalog zone may exist.

Common situations: Manual deletion of the cluster zone; partial cleanup from a failed join or prior promotion; zone file lost from disk; cluster domain mismatch.

Related errors

• Failed to promote to Primary node: the Cluster Secondary Cat
• Failed to update Primary node: the Cluster Secondary Catalog
• Failed to promote to Primary node: the Cluster Primary zone
• Failed to promote to Primary node: the Cluster is not initia
• 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/6b44276a7fb45995. Report an issue: GitHub.