TechnitiumSoftware/DnsServer · error · ArgumentException

Failed to update Cluster options: The config refresh interva

Error message

Failed to update Cluster options: The config refresh interval must be greater than the heartbeat refresh interval.

What it means

UpdateClusterOptions rejects the values because configRefreshIntervalSeconds is not greater than heartbeatRefreshIntervalSeconds (configRefreshIntervalSeconds <= heartbeatRefreshIntervalSeconds). The config refresh cadence must be slower than heartbeats so health is detected before a config pull.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:920

                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.");

            bool changed = false;

            if (_heartbeatRefreshIntervalSeconds != heartbeatRefreshIntervalSeconds)
            {
                _heartbeatRefreshIntervalSeconds = heartbeatRefreshIntervalSeconds;
                changed = true;
            }

            if (_heartbeatRetryIntervalSeconds != heartbeatRetryIntervalSeconds)
            {
                _heartbeatRetryIntervalSeconds = heartbeatRetryIntervalSeconds;
                changed = true;
            }

            if (_configRefreshIntervalSeconds != configRefreshIntervalSeconds)
            {
                _configRefreshIntervalSeconds = configRefreshIntervalSeconds;

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Make configRefreshIntervalSeconds strictly greater than heartbeatRefreshIntervalSeconds
2. Re-balance both within their bounds (heartbeat 10-300s, config 30-3600s)
3. Validate the invariant in the UI before submit

Example fix

// before
clusterManager.UpdateClusterOptions(
    heartbeatRefreshIntervalSeconds: 60,
    heartbeatRetryIntervalSeconds: 15,
    configRefreshIntervalSeconds: 60, // <= heartbeat: invalid
    configRetryIntervalSeconds: 30);

// after
clusterManager.UpdateClusterOptions(
    heartbeatRefreshIntervalSeconds: 30,
    heartbeatRetryIntervalSeconds: 15,
    configRefreshIntervalSeconds: 300, // > heartbeat
    configRetryIntervalSeconds: 60);

if (configRefreshIntervalSeconds <= heartbeatRefreshIntervalSeconds)
    return BadRequest("config refresh must be greater than heartbeat refresh.");
if (heartbeatRefreshIntervalSeconds is < 10 or > 300) return BadRequest("heartbeat out of range.");
if (configRefreshIntervalSeconds is < 30 or > 3600) return BadRequest("config out of range.");
clusterManager.UpdateClusterOptions(heartbeatRefreshIntervalSeconds, heartbeatRetryIntervalSeconds, configRefreshIntervalSeconds, configRetryIntervalSeconds);

catch (ArgumentException ex) when (ex.Message.Contains("config refresh interval must be greater"))
{ /* surface to UI: raise config or lower heartbeat */ }

When it happens

Trigger: Setting config refresh equal to or faster than heartbeat; lowering heartbeat without raising config; UI defaults that violate the invariant.

Common situations: Misordered sliders; importing a config with swapped intervals; tightening heartbeats to catch failures faster and forgetting to relax config.

Related errors

• Failed to update Cluster options: the Cluster is not initial
• Failed to delete Secondary node: the specified node is the C
• Failed to update Secondary node: the Cluster is not initiali
• Failed to update Secondary node: only a Primary node can upd
• Failed to update Secondary node: the specified node does not

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