TechnitiumSoftware/DnsServer · error · HttpApiClientException

Unknown status value was received

Error message

Unknown status value was received: {status}

What it means

CheckResponseStatus switches on the lowercased 'status' string and handles 'ok', 'error', 'invalid-token', and '2fa-required'. This HttpApiClientException fires for any other status value, indicating the server spoke a status dialect the client does not understand (version skew or a malformed response).

Solutions

1. Upgrade the HttpApiClient package to match the deployed DNS Server version.
2. Log the received 'status' value to identify what the server sent.
3. If running a custom server build, align its status vocabulary with the client's switch cases.

static readonly HashSet<string> KnownStatuses = new()
{
    "ok", "error", "invalid-token", "2fa-required"
};

// after parsing rootElement:
if (rootElement.TryGetProperty("status", out var s)
    && !KnownStatuses.Contains(s.GetString()?.ToLowerInvariant() ?? ""))
{
    // version skew: client cannot handle this status
}

catch (HttpApiClientException ex) when (ex.Message.StartsWith("Unknown status value was received"))
{
    logger.LogError("Version skew: server sent an unrecognised status. Upgrade HttpApiClient.");
}

When it happens

Trigger: The server returns JSON with a 'status' field whose value is not one of ok/error/invalid-token/2fa-required — e.g. a newer server emitting 'partial', 'pending', or a typo'd status.

Common situations: Client library is older than the server (or vice versa) introducing new status codes; a forked/customized server added statuses the stock client does not recognise.

Related errors

• Invalid JSON response was received.
• Already logged in.
• Already logged in. Please create a new object to use a…
• At least one parameter must be provided.
• No active session exist to logout.

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

Appendix: source

Thrown at DnsServerCore.HttpApi/HttpApiClient.cs:161

                case "invalid-token":
                    {
                        if (rootElement.TryGetProperty("errorMessage", out JsonElement jsonErrorMessage))
                            throw new InvalidTokenHttpApiClientException(jsonErrorMessage.GetString()!);

                        throw new InvalidTokenHttpApiClientException();
                    }

                case "2fa-required":
                    {
                        if (rootElement.TryGetProperty("errorMessage", out JsonElement jsonErrorMessage))
                            throw new TwoFactorAuthRequiredHttpApiClientException(jsonErrorMessage.GetString()!);

                        throw new TwoFactorAuthRequiredHttpApiClientException();
                    }

                default:
                    throw new HttpApiClientException("Unknown status value was received: " + status);
            }
        }

        #endregion

        #region public

        public async Task<SessionInfo> LoginAsync(string username, string password, string? totp = null, bool includeInfo = false, CancellationToken cancellationToken = default)
        {
            if (_loggedIn)
                throw new HttpApiClientException("Already logged in.");

            HttpRequestMessage httpRequest = new HttpRequestMessage(HttpMethod.Post, new Uri(_serverUrl, $"api/user/login"));

            Dictionary<string, string> parameters = new Dictionary<string, string>
            {
                { "user", username },
                { "pass", password },

View on GitHub (pinned to d0484b6c1e)