TechnitiumSoftware/DnsServer · warning · DnsServerException

Failed to refresh configuration: the Cluster is not…

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.

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);
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

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

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

Appendix: 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)