{"record":{"id":"1cd0599dad974c3b","repo":"TechnitiumSoftware/DnsServer","slug":"failed-to-initialize-cluster-failed-to-create-the","errorCode":null,"errorMessage":"Failed to initialize Cluster: failed to create the Cluster zone '{clusterDomain}'. Please try again.","messagePattern":"Failed to initialize Cluster: failed to create the Cluster zone '(.+?)'\\. Please try again\\.","errorType":"exception","errorClass":"DnsServerException","httpStatus":null,"severity":"error","filePath":"DnsServerCore/Cluster/ClusterManager.cs","lineNumber":554,"sourceCode":"            {\n                int x = serverDomain.IndexOf('.');\n                if (x < 0)\n                    serverDomain = serverDomain + \".\" + clusterDomain;\n                else\n                    serverDomain = string.Concat(serverDomain.AsSpan(0, x), \".\", clusterDomain);\n            }\n\n            Uri primaryNodeUrl = new Uri($\"https://{serverDomain}:{_dnsWebService.WebServiceTlsPort}/\");\n\n            ClusterNode selfPrimaryNode = new ClusterNode(this, RandomNumberGenerator.GetInt32(int.MaxValue), primaryNodeUrl, primaryNodeIpAddresses, ClusterNodeType.Primary, ClusterNodeState.Self);\n\n            //create cluster primary zone\n            AuthZoneInfo clusterZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(clusterDomain);\n            if (clusterZoneInfo is null)\n            {\n                clusterZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.CreatePrimaryZone(clusterDomain);\n                if (clusterZoneInfo is null)\n                    throw new DnsServerException($\"Failed to initialize Cluster: failed to create the Cluster zone '{clusterDomain}'. Please try again.\");\n            }\n            else if (clusterZoneInfo.Type != AuthZoneType.Primary)\n            {\n                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.\");\n            }\n\n            //create cluster catalog zone\n            string clusterCatalogDomain = \"cluster-catalog.\" + clusterDomain;\n\n            AuthZoneInfo clusterCatalogZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.GetAuthZoneInfo(clusterCatalogDomain);\n            if (clusterCatalogZoneInfo is null)\n            {\n                clusterCatalogZoneInfo = _dnsWebService.DnsServer.AuthZoneManager.CreateCatalogZone(clusterCatalogDomain);\n                if (clusterCatalogZoneInfo is null)\n                    throw new DnsServerException($\"Failed to initialize Cluster: failed to create the Cluster Catalog zone '{clusterCatalogDomain}'. Please try again.\");\n            }\n            else if (clusterCatalogZoneInfo.Type != AuthZoneType.Catalog)\n            {","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/TechnitiumSoftware/DnsServer/blob/d0484b6c1e7439cdc53d67d81e9c876cda2ad756/DnsServerCore/Cluster/ClusterManager.cs#L536-L572","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry initialization in case the failure was transient (disk/I/O).","Validate clusterDomain is a well-formed DNS name (FQDN, valid labels, reasonable length) before calling InitializeCluster.","Check DNS server logs/zone store permissions and free space, then retry."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if (!IsWellFormedDnsName(clusterDomain))\n    return BadRequest(\"clusterDomain must be a valid DNS name.\");\n// then attempt initialization; retry on transient zone-creation failure","typeGuard":"static bool IsWellFormedDnsName(string name) =>\n    !string.IsNullOrWhiteSpace(name)\n    && Uri.CheckHostName(name) == UriHostNameType.Dns\n    && name.Length <= 253\n    && name.Split('.').All(l => l.Length >= 1 && l.Length <= 63);","tryCatchPattern":null,"preventionTips":["Validate clusterDomain as a well-formed FQDN before initialization.","Retry once for transient I/O failures during zone creation.","Check DNS zone-store permissions and free disk space before clustering."],"tags":["cluster","dns-zone","initialization","validation","technitium-dns-server"],"backgroundTag":null,"analyzedSha":"d0484b6c1e7439cdc53d67d81e9c876cda2ad756","analyzedAt":"2026-08-13T22:57:35.508Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}