TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to initialize Cluster: failed to create the Cluster z

Error message

Failed to initialize Cluster: failed to create the Cluster zone '{clusterDomain}'. Please try again.

What it means

Thrown by ClusterManager.InitializeCluster when AuthZoneManager.CreatePrimaryZone(clusterDomain) returns null after GetAuthZoneInfo confirmed no zone exists with that name. A null return means the zone manager refused to create the zone (e.g. invalid domain syntax, a name conflict surfaced internally, or an I/O failure during zone creation). Because the cluster cannot function without its primary zone, initialization aborts after the zone-creation failure.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:554

            {
                int x = serverDomain.IndexOf('.');
                if (x < 0)
                    serverDomain = serverDomain + "." + clusterDomain;
                else
                    serverDomain = string.Concat(serverDomain.AsSpan(0, x), ".", clusterDomain);
            }

            Uri primaryNodeUrl = new Uri($"https://{serverDomain}:{_dnsWebService.WebServiceTlsPort}/");

            ClusterNode selfPrimaryNode = new ClusterNode(this, RandomNumberGenerator.GetInt32(int.MaxValue), primaryNodeUrl, primaryNodeIpAddresses, ClusterNodeType.Primary, ClusterNodeState.Self);

            //create cluster primary zone
            AuthZoneInfo clusterZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(clusterDomain);
            if (clusterZoneInfo is null)
            {
                clusterZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.CreatePrimaryZone(clusterDomain);
                if (clusterZoneInfo is null)
                    throw new DnsServerException($"Failed to initialize Cluster: failed to create the Cluster zone '{clusterDomain}'. Please try again.");
            }
            else if (clusterZoneInfo.Type != AuthZoneType.Primary)
            {
                throw new DnsServerException($"Failed to initialize Cluster: the zone '{clusterZoneInfo.Name}' already exists and is not a Primary zone. Please delete the existing zone or use a different Cluster domain name.");
            }

            //create cluster catalog zone
            string clusterCatalogDomain = "cluster-catalog." + clusterDomain;

            AuthZoneInfo clusterCatalogZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(clusterCatalogDomain);
            if (clusterCatalogZoneInfo is null)
            {
                clusterCatalogZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.CreateCatalogZone(clusterCatalogDomain);
                if (clusterCatalogZoneInfo is null)
                    throw new DnsServerException($"Failed to initialize Cluster: failed to create the Cluster Catalog zone '{clusterCatalogDomain}'. Please try again.");
            }
            else if (clusterCatalogZoneInfo.Type != AuthZoneType.Catalog)
            {

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Retry initialization in case the failure was transient (disk/I/O).
2. Validate clusterDomain is a well-formed DNS name (FQDN, valid labels, reasonable length) before calling InitializeCluster.
3. Check DNS server logs/zone store permissions and free space, then retry.

if (!IsWellFormedDnsName(clusterDomain))
    return BadRequest("clusterDomain must be a valid DNS name.");
// then attempt initialization; retry on transient zone-creation failure

static bool IsWellFormedDnsName(string name) =>
    !string.IsNullOrWhiteSpace(name)
    && Uri.CheckHostName(name) == UriHostNameType.Dns
    && name.Length <= 253
    && name.Split('.').All(l => l.Length >= 1 && l.Length <= 63);

When it happens

Trigger: Calling InitializeCluster with a clusterDomain that is malformed, contains invalid labels, exceeds DNS name limits, or collides with internal constraints that cause CreatePrimaryZone to fail and return null.

Common situations: Typo in the cluster domain; using a root/empty label; the DNS server's zone store is read-only or out of space; a transient I/O error during zone file creation.

Related errors

• Failed to initialize Cluster: the Cluster is already initial
• Failed to initialize Cluster: a SSO user cannot initialize c
• Failed to initialize Cluster: the zone '{clusterZoneInfo.Nam
• Failed to initialize Cluster: the zone '{clusterCatalogZoneI
• Invalid time-based one-time password (TOTP) was attempted fo

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