TechnitiumSoftware/DnsServer · error · DnsServerException

Failed to initialize Cluster: a SSO user cannot initialize c

Error message

Failed to initialize Cluster: a SSO user cannot initialize cluster. Please login with a local administrator user account and try again.

What it means

Thrown by ClusterManager.InitializeCluster when the session's user is an SSO user. Bootstrapping a cluster creates primary/catalog DNS zones and rewrites server configuration, which requires a local administrator whose credentials are fully under the server's control; an SSO user's privileges and session lifetime are governed externally and cannot be trusted for this destructive, one-time operation. DnsServerException (not InvalidOperationException) is used so the API surfaces a user-facing message.

Source

Thrown at DnsServerCore/Cluster/ClusterManager.cs:529

            _dnsWebService.AuthManager.SaveConfigFile();

            UnloadAndDeleteConfigFile();
        }

        #endregion

        #region primary node

        public void InitializeCluster(string clusterDomain, IReadOnlyList<IPAddress> primaryNodeIpAddresses, UserSession session)
        {
            if (ClusterInitialized)
                throw new DnsServerException("Failed to initialize Cluster: the Cluster is already initialized.");

            if (!_dnsWebService.IsWebServiceTlsEnabled)
                throw new InvalidOperationException();

            if (session.User.IsSsoUser)
                throw new DnsServerException("Failed to initialize Cluster: a SSO user cannot initialize cluster. Please login with a local administrator user account and try again.");

            clusterDomain = clusterDomain.ToLowerInvariant();

            //create self node
            string serverDomain = _dnsWebService.DnsServer.ServerDomain;
            if (!serverDomain.EndsWith("." + clusterDomain, StringComparison.OrdinalIgnoreCase))
            {
                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);

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Log in with a local administrator account (not SSO) before running cluster initialization.
2. Ensure at least one local admin account exists before enabling SSO.
3. Gate the 'initialize cluster' UI action on the session user being a local admin.

if (session.User.IsSsoUser)
    return BadRequest("Log in with a local administrator account to initialize the cluster.");
clusterManager.InitializeCluster(domain, ips, session);

static bool CanInitializeCluster(ClusterManager cm, UserSession s) => !cm.ClusterInitialized && !s.User.IsSsoUser;

When it happens

Trigger: An administrator logged in via SSO attempts to initialize the cluster through the web API. The guard fires after the already-initialized and TLS-enabled checks, before any cluster domain processing.

Common situations: A site that uses SSO exclusively for admin login; an SSO user with admin role tries cluster setup without realizing local creds are required; SSO session outlives a switch back to local auth.

Related errors

• Cannot change password for SSO users.
• Time-based one-time password (TOTP) feature is not available
• Failed to initialize Cluster: the Cluster is already initial
• Failed to initialize Cluster: failed to create the Cluster z
• Time-based one-time password (TOTP) is already enabled for u

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