TechnitiumSoftware/DnsServer · error · InvalidOperationException

No API token was found for the Cluster domain.

Error message

No API token was found for the Cluster domain.

What it means

Thrown by ClusterNode.GetApiClient() (InvalidOperationException) when no UserSession of type UserSessionType.ClusterApiToken exists in AuthManager.Sessions. The cluster API token is the credential a node uses to authenticate inter-node REST calls; without it the HttpApiClient cannot be created. The token is normally provisioned by ClusterManager during init (it auto-upgrades an admin API token named after the cluster domain) — this error means that provisioning failed or the token was deleted.

Source

Thrown at DnsServerCore/Cluster/ClusterNode.cs:210

                throw new InvalidOperationException();

            if (_apiClient is null)
            {
                HttpApiClient apiClient = new HttpApiClient(_url, _clusterManager.DnsWebService.DnsServer.Proxy, _clusterManager.DnsWebService.DnsServer.IPv6Mode, false, new InternalDnsClient(_clusterManager.DnsWebService.DnsServer, this));

                UserSession clusterApiToken = null;

                foreach (UserSession session in _clusterManager.DnsWebService.AuthManager.Sessions)
                {
                    if (session.Type == UserSessionType.ClusterApiToken)
                    {
                        clusterApiToken = session;
                        break;
                    }
                }

                if (clusterApiToken is null)
                    throw new InvalidOperationException("No API token was found for the Cluster domain.");

                apiClient.UseApiToken(clusterApiToken.Token);

                _apiClient = apiClient;
            }

            return _apiClient;
        }

        private async void HeartbeatTimerCallbackAsync(object state)
        {
            bool success = true;

            try
            {
                ClusterInfo clusterInfo = await GetClusterStateAsync();

                if (_type == ClusterNodeType.Primary)

View on GitHub (pinned to d0484b6c1e)

Solutions

1. Re-create the cluster API token: in the web UI create an admin API token named after the cluster domain, then restart / re-init the cluster so it is upgraded to a ClusterApiToken.
2. Verify the owning user still exists and is a member of the Administrators group.
3. Restart the DNS server service so ClusterManager's startup token-repair logic (ClusterManager.cs:124-148) re-runs.
4. Check AuthManager.Sessions at runtime to confirm whether a ClusterApiToken session is present before issuing inter-node calls.

Example fix

// before: cluster enabled but token was deleted -> any inter-node call throws [204]
await node.GetClusterStateAsync(); // InvalidOperationException

// after: re-provision the token (admin API token named = cluster domain), then restart
authManager.CreateSession(UserSessionType.ApiToken, clusterDomain, adminUsername, remoteAddress, userAgent);
// restart service; on init ClusterManager upgrades it to ClusterApiToken
await node.GetClusterStateAsync(); // ok

// Before any inter-node API call, confirm the cluster API token session exists
bool hasToken = _clusterManager.DnsWebService.AuthManager.Sessions
    .Any(s => s.Type == UserSessionType.ClusterApiToken);

if (!hasToken)
    throw new InvalidOperationException("Cluster API token missing; re-provision it before cluster operations.");

try
{
    await node.GetClusterStateAsync(cancellationToken);
}
catch (InvalidOperationException ex) when (ex.Message == "No API token was found for the Cluster domain.")
{
    // trigger token re-provisioning / alert admin, then retry once
    logger.LogError("Cluster API token missing for node {Node}.", node);
    throw;
}

When it happens

Trigger: Any inter-node API call (GetClusterStateAsync, SyncConfigAsync, ProxyRequest, dashboard stats, etc.) on a non-self node that triggers GetApiClient() when the cluster API token session is missing from AuthManager.

Common situations: The admin user that owned the cluster API token was deleted; the token was revoked via the auth API; a config migration/import skipped the token upgrade step; cluster was enabled but the matching admin API token (named = cluster domain) never existed to be upgraded.

Related errors

• Failed to initialize Cluster: a SSO user cannot initialize c
• Failed to update Cluster options: the Cluster is not initial
• Failed to update Cluster options: only the Primary node can
• Failed to update Cluster options: The config refresh interva
• Failed to update self node URL: the node's domain name alrea

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