TechnitiumSoftware/DnsServer · warning · DnsServerException

Failed to refresh configuration: the Cluster is not initiali

Error message

Failed to refresh configuration: the Cluster is not initialized.

What it means

Thrown at the top of the public TriggerRefreshForConfig(IReadOnlyCollection<string>) overload when ClusterInitialized is false. Config refresh pulls configuration from a primary node, which requires an active cluster; on a standalone server there is nothing to refresh from.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:1608

            //update cluster catalog zone's primary name server
            clusterSecondaryCatalogZoneInfo.PrimaryNameServerAddresses = primaryNodeIpAddresses.Convert(delegate (IPAddress ipAddress) { return new NameServerAddress(primaryNodeUrl.Host, ipAddress); });

            //save all changes
            _dnsWebService.DnsServer.AuthZoneManager.SaveZoneFile(clusterSecondaryCatalogZoneInfo.Name);
            SaveConfigFile();

            //trigger config and zone refresh
            TriggerRefreshForConfig(CONFIG_REFRESH_TIMER_INTERVAL);

            return primaryNode;
        }

        public void TriggerRefreshForConfig(IReadOnlyCollection<string> configRefreshIncludeZones = null)
        {
            //do validation
            if (!ClusterInitialized)
                throw new DnsServerException("Failed to refresh configuration: the Cluster is not initialized.");

            ClusterNode primaryNode = GetPrimaryNode();

            if (primaryNode.State == ClusterNodeState.Self)
                throw new DnsServerException("Failed to refresh configuration: only Secondary nodes can sync configuration from Primary nodes.");

            TriggerRefreshForConfig(CONFIG_REFRESH_TIMER_INTERVAL, configRefreshIncludeZones);
        }

        public void TriggerResyncForConfig()
        {
            //do validation
            if (!ClusterInitialized)
                throw new DnsServerException("Failed to resync configuration: the Cluster is not initialized.");

            ClusterNode primaryNode = GetPrimaryNode();

            if (primaryNode.State == ClusterNodeState.Self)

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Gate the call on ClusterInitialized and surface 'not clustered' to the user instead of invoking.
2. If clustering was expected, restore/rejoin the cluster before refreshing.
3. Disable the refresh-config control in the UI whenever ClusterInitialized is false.

Example fix

// before
clusterManager.TriggerRefreshForConfig(includeZones);

// after
if (!clusterManager.ClusterInitialized)
    return BadRequest("Not clustered; nothing to refresh.");
clusterManager.TriggerRefreshForConfig(includeZones);

if (!clusterManager.ClusterInitialized)
    return BadRequest("Not clustered; nothing to refresh.");
clusterManager.TriggerRefreshForConfig(includeZones);

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

try { clusterManager.TriggerRefreshForConfig(includeZones); }
catch (DnsServerException ex) when (ex.Message.Contains("not initialized"))
{ /* not clustered; no-op */ }

When it happens

Trigger: Calling TriggerRefreshForConfig (e.g. from a 'refresh config now' button) on a node that is not part of any cluster.

Common situations: UI/API 'refresh configuration' invoked on a primary-only standalone server; the node had left the cluster but the action was still available; cluster config lost between page load and click.

Related errors

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

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