TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to update Cluster options: the Cluster is not initial

Error message

Failed to update Cluster options: the Cluster is not initialized.

What it means

UpdateClusterOptions requires an active cluster (ClusterInitialized true). Cluster-wide timing options (heartbeat/config intervals) only exist once the cluster is set up.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:902

                                                    dnsSettings: true,
                                                    logSettings: false,
                                                    zones: true,
                                                    allowedZones: true,
                                                    blockedZones: true,
                                                    blockLists: true,
                                                    apps: true,
                                                    scopes: false,
                                                    stats: false,
                                                    logs: false,
                                                    isConfigTransfer: true,
                                                    ifModifiedSince: ifModifiedSince,
                                                    includeZones: includeZones);
        }

        public void UpdateClusterOptions(ushort heartbeatRefreshIntervalSeconds, ushort heartbeatRetryIntervalSeconds, ushort configRefreshIntervalSeconds, ushort configRetryIntervalSeconds)
        {
            if (!ClusterInitialized)
                throw new DnsServerException("Failed to update Cluster options: the Cluster is not initialized.");

            if (GetSelfNode().Type != ClusterNodeType.Primary)
                throw new DnsServerException("Failed to update Cluster options: only the Primary node can update the Cluster options.");

            if ((heartbeatRefreshIntervalSeconds < 10) || (heartbeatRefreshIntervalSeconds > 300))
                throw new ArgumentOutOfRangeException(nameof(heartbeatRefreshIntervalSeconds));

            if ((heartbeatRetryIntervalSeconds < 10) || (heartbeatRetryIntervalSeconds > 300))
                throw new ArgumentOutOfRangeException(nameof(heartbeatRetryIntervalSeconds));

            if ((configRefreshIntervalSeconds < 30) || (configRefreshIntervalSeconds > 3600))
                throw new ArgumentOutOfRangeException(nameof(configRefreshIntervalSeconds));

            if ((configRetryIntervalSeconds < 30) || (configRetryIntervalSeconds > 3600))
                throw new ArgumentOutOfRangeException(nameof(configRetryIntervalSeconds));

            if (configRefreshIntervalSeconds <= heartbeatRefreshIntervalSeconds)
                throw new ArgumentException("Failed to update Cluster options: The config refresh interval must be greater than the heartbeat refresh interval.");

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Initialize the cluster on the Primary first
2. Confirm ClusterInitialized before tuning
3. Re-run init if it failed

Example fix

// before
clusterManager.UpdateClusterOptions(hb, hbRetry, cfg, cfgRetry);

// after
if (!clusterManager.ClusterInitialized)
    throw new InvalidOperationException("Cluster not initialized.");
clusterManager.UpdateClusterOptions(hb, hbRetry, cfg, cfgRetry);

if (!clusterManager.ClusterInitialized)
    return BadRequest("Cluster not initialized; cannot update options.");
clusterManager.UpdateClusterOptions(hb, hbRetry, cfg, cfgRetry);

catch (DnsServerException ex) when (ex.Message.Contains("Cluster is not initialized"))
{ /* init cluster or redirect to Primary */ }

When it happens

Trigger: Calling UpdateClusterOptions on a standalone or not-yet-initialized node; after the cluster was left or reset.

Common situations: Calling the tuning endpoint before CreateCluster completes; targeting the wrong server; an init failure leaving ClusterInitialized false.

Related errors

• Failed to update Secondary node: the Cluster is not initiali
• Failed to transfer configuration: the Cluster is not initial
• Failed to update Cluster options: The config refresh interva
• Failed to join Cluster: the Cluster is already initialized.
• Failed to join Cluster: the Primary node does not have a Clu

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