{"record":{"id":"0da8b7b3e90b0af6","repo":"TechnitiumSoftware/DnsServer","slug":"failed-to-initialize-cluster-failed-to-create-the-0da8b7","errorCode":null,"errorMessage":"Failed to initialize Cluster: failed to create the Cluster Catalog zone '{clusterCatalogDomain}'. Please try again.","messagePattern":"Failed to initialize Cluster: failed to create the Cluster Catalog zone '(.+?)'\\. Please try again\\.","errorType":"exception","errorClass":"DnsServerException","httpStatus":null,"severity":"error","filePath":"DnsServerCore/Cluster/ClusterManager.cs","lineNumber":569,"sourceCode":"            {\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            {\n                throw new DnsServerException($\"Failed to initialize Cluster: the zone '{clusterCatalogZoneInfo.Name}' already exists and is not a Catalog zone. Please delete the existing zone or use a different Cluster domain name.\");\n            }\n\n            //set cluster primary zone permissions\n            _dnsWebService.AuthManager.SetPermission(PermissionSection.Zones, clusterZoneInfo.Name, _dnsWebService.AuthManager.GetGroup(Group.ADMINISTRATORS), PermissionFlag.ViewModifyDelete);\n            _dnsWebService.AuthManager.SetPermission(PermissionSection.Zones, clusterZoneInfo.Name, _dnsWebService.AuthManager.GetGroup(Group.DNS_ADMINISTRATORS), PermissionFlag.View);\n\n            //set cluster catalog zone permissions\n            _dnsWebService.AuthManager.SetPermission(PermissionSection.Zones, clusterCatalogZoneInfo.Name, _dnsWebService.AuthManager.GetGroup(Group.ADMINISTRATORS), PermissionFlag.ViewModifyDelete);\n            _dnsWebService.AuthManager.SetPermission(PermissionSection.Zones, clusterCatalogZoneInfo.Name, _dnsWebService.AuthManager.GetGroup(Group.DNS_ADMINISTRATORS), PermissionFlag.View);\n\n            //ensure cluster zone is a member of cluster catalog zone\n            if (clusterZoneInfo.CatalogZoneName is null)\n                _dnsWebService.DnsServer.AuthZoneManager.AddCatalogMemberZone(clusterCatalogZoneInfo.Name, clusterZoneInfo);\n            else if (!clusterZoneInfo.CatalogZoneName.Equals(clusterCatalogZoneInfo.Name, StringComparison.OrdinalIgnoreCase))","sourceCodeStart":551,"sourceCodeEnd":587,"githubUrl":"https://github.com/TechnitiumSoftware/DnsServer/blob/d0484b6c1e7439cdc53d67d81e9c876cda2ad756/DnsServerCore/Cluster/ClusterManager.cs#L551-L587","documentation":"Thrown by InitializeCluster when AuthZoneManager.CreateCatalogZone(clusterCatalogDomain) returns null instead of throwing. The catalog zone (prefixed 'cluster-catalog.') is required for zone replication across cluster nodes. A null return is an internal failure inside CreateCatalogZone that the cluster manager surfaces as a user-facing error with a retry suggestion.","triggerScenarios":"InitializeCluster reaches the catalog-zone creation branch (line 567) only when GetAuthZoneInfo returns null for the catalog domain, and CreateCatalogZone then returns null. This indicates an internal failure in the zone manager — typically I/O, validation rejection, or resource limits — rather than a naming conflict.","commonSituations":"Filesystem permission denied or disk full when writing the catalog zone file; concurrent zone operations holding a lock; transient I/O error; corrupted zone directory state.","solutions":["Retry InitializeCluster — the message explicitly says 'Please try again' and the failure may be transient.","Check the DNS server application logs for the underlying exception or null-return reason inside CreateCatalogZone.","Verify write permissions and free disk space on the DNS configuration/zone directory.","Ensure no concurrent zone management operations are running that could conflict."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"for (int attempt = 0; attempt < 3; attempt++)\n{\n    try\n    {\n        _dnsWebService.ClusterManager.InitializeCluster(clusterDomain, ips, session);\n        break;\n    }\n    catch (DnsServerException ex) when (ex.Message.Contains(\"failed to create the Cluster Catalog zone\"))\n    {\n        if (attempt == 2) throw;\n        await Task.Delay(500 * (attempt + 1));\n    }\n}","preventionTips":["Ensure the DNS config/zone directory is writable and has adequate free disk space.","Avoid running concurrent zone-creation operations during cluster initialization.","Monitor server logs for CreateCatalogZone internals when this error recurs."],"tags":["cluster","dns-zone","catalog","retry","transient"],"backgroundTag":null,"analyzedSha":"d0484b6c1e7439cdc53d67d81e9c876cda2ad756","analyzedAt":"2026-08-13T22:57:35.508Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}