TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to add Secondary node: a maximum of 255 nodes are sup

Error message

Failed to add Secondary node: a maximum of 255 nodes are supported by the Cluster.

What it means

Thrown by JoinCluster when adding the new node would bring the total node count above 255. The cluster uses byte-sized node identifiers and zone-record structures that cap at 255 members, so this is a hard architectural limit enforced after the TryAdd succeeds but before the CompareExchange commits.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:716

            //validate for duplicate names
            foreach (KeyValuePair<int, ClusterNode> existingClusterNode in existingClusterNodes)
            {
                if (existingClusterNode.Value.Name.Equals(secondaryNodeUrl.Host, StringComparison.OrdinalIgnoreCase))
                    throw new DnsServerException("Failed to add Secondary node: A node with the same DNS Server Domain Name already exists in the Cluster. Please try again after changing the Secondary node's DNS Server Domain Name.");
            }

            //add secondary node to cluster nodes
            ClusterNode secondaryNode = new ClusterNode(this, secondaryNodeId, secondaryNodeUrl, secondaryNodeIpAddresses, ClusterNodeType.Secondary, ClusterNodeState.Unknown);
            Dictionary<int, ClusterNode> updatedClusterNodes = new Dictionary<int, ClusterNode>(existingClusterNodes.Count + 1);

            foreach (KeyValuePair<int, ClusterNode> existingClusterNode in existingClusterNodes)
                updatedClusterNodes[existingClusterNode.Value.Id] = existingClusterNode.Value;

            if (!updatedClusterNodes.TryAdd(secondaryNode.Id, secondaryNode))
                throw new DnsServerException("Failed to add Secondary node: node ID already exists in the Cluster. Please try again.");

            if (updatedClusterNodes.Count > 255)
                throw new DnsServerException("Failed to add Secondary node: a maximum of 255 nodes are supported by the Cluster.");

            IReadOnlyDictionary<int, ClusterNode> originalValue = Interlocked.CompareExchange(ref _clusterNodes, updatedClusterNodes, existingClusterNodes);
            if (!ReferenceEquals(originalValue, existingClusterNodes))
                throw new DnsServerException("Failed to add Secondary node: please try again.");

            secondaryNode.InitializeHeartbeatTimer();

            //update cluster zone and save zone file
            FindExistingRecordTtlValues(out uint nsTtl, out uint aTtl); //find existing record TTL values
            AddClusterPrimaryZoneRecordsFor(secondaryNode, nsTtl, aTtl, secondaryNodeCertificate);

            //update cluster catalog zone ACLs and save zone file
            UpdateClusterCatalogZoneOptions();

            //save all changes
            SaveConfigFile();

            //notify all secondary nodes

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Remove unused or offline Secondary nodes (via DeleteSecondaryNode) before adding new ones to stay within 255.
2. Redesign the DNS topology so no single cluster exceeds 255 nodes (split into multiple clusters or reduce redundancy).

const int MAX_CLUSTER_NODES = 255;
if (_dnsWebService.ClusterManager.ClusterNodes.Count >= MAX_CLUSTER_NODES)
    throw new InvalidOperationException($"Cluster is at the {MAX_CLUSTER_NODES}-node limit; remove a Secondary before adding another.");
_dnsWebService.ClusterManager.JoinCluster(nodeId, nodeUrl, nodeIps, cert);

static bool HasClusterCapacity(ClusterManager cm, int max = 255)
    => cm.ClusterNodes.Count < max;

try
{
    _clusterManager.JoinCluster(nodeId, nodeUrl, nodeIps, cert);
}
catch (DnsServerException ex) when (ex.Message.Contains("maximum of 255 nodes"))
{
    throw new InvalidOperationException("Cluster node limit reached. Remove unused Secondaries or split into multiple clusters.", ex);
}

When it happens

Trigger: JoinCluster adds a node to updatedClusterNodes and then checks updatedClusterNodes.Count > 255 at line 715. If the existing cluster already has 255 nodes, the 256th triggers this error.

Common situations: Large-scale deployment attempting to exceed the documented 255-node ceiling; automated scaling script that does not track the node count.

Related errors

• Failed to add Secondary node: the Cluster is not initialized
• Failed to add Secondary node: only a Primary node can add a
• Failed to add Secondary node: the Secondary node domain name
• Failed to add Secondary node: A node with the same DNS Serve
• Failed to add Secondary node: node ID already exists in the

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