BornToBeRoot/NETworkManager · error · DNSClientNotConfiguredException

DNS client is not configured. Call Configure() first.

Error message

DNS client is not configured. Call Configure() first.

What it means

DNSClient.ResolveAAsync performs an A record lookup, but the client must first be initialized with Configure() (which creates the internal LookupClient and state). If _isConfigured is false, it throws DNSClientNotConfiguredException with the message 'DNS client is not configured. Call Configure() first.'

Solutions

1. Call Configure() (with the desired DNS servers, or none for system defaults) before any Resolve* call
2. Ensure the application's initialization path that configures DNSClient actually runs before DNS-dependent features
3. Guard call sites: expose an IsConfigured check or lazily call Configure on first use
4. In tests, configure the client in the fixture setup

Example fix

// before
var dns = new DNSClient();
var result = await dns.ResolveAAsync("example.com"); // throws
// after
var dns = new DNSClient();
dns.Configure();
var result = await dns.ResolveAAsync("example.com");

if (!_dnsClient.IsConfigured) _dnsClient.Configure();

bool ReadyForQueries(DNSClient c) => c != null && c.IsConfigured;

try { var r = await dns.ResolveAAsync(query); }
catch (DNSClientNotConfiguredException) { dns.Configure(); var r = await dns.ResolveAAsync(query); }

When it happens

Trigger: Calling ResolveAAsync on a newly constructed DNSClient instance without ever calling Configure(), or after reconfiguration logic failed to run / was skipped on the initialization path.

Common situations: Instantiating DNSClient in a new ViewModel/tool without wiring the app's Configure call (which reads DNS servers from settings); using the client in a unit test without setup; calling resolve before settings load completes.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Error while retrieving TCP table
• Win32Exception for native error code (int)result
• message (joined PowerShell error streams)
• Active Directory search failed for

AI-assisted analysis of BornToBeRoot/NETworkManager@2780d65469 (2026-09-12). Data as JSON: /api/errors/fddb91219ae037be. Report an issue: GitHub.

Appendix: source

Thrown at Source/NETworkManager.Utilities/DNSClient.cs:90

        Log.Debug(addSuffix
            ? $"Configure - DNS suffix will be added to hostnames without a dot: {settings.DNSSuffix}"
            : "Configure - DNS suffix will NOT be added to hostnames without a dot.");

        _state = new ResolverState(client, addSuffix, settings);

        Log.Debug("Configure - DNS client configured.");
        _isConfigured = true;
    }

    /// <summary>
    ///     Resolve an IPv4 address from a hostname or FQDN.
    /// </summary>
    /// <param name="query">Hostname or FQDN as string like "example.com".</param>
    /// <returns><see cref="IPAddress" /> of the host.</returns>
    public async Task<DNSClientResultIPAddress> ResolveAAsync(string query)
    {
        if (!_isConfigured)
            throw new DNSClientNotConfiguredException(NotConfiguredMessage);

        var state = _state;

        query = AddDNSSuffixIfConfigured(query, state);

        try
        {
            var result = await state.Client.QueryAsync(query, QueryType.A);

            // Pass the error we got from the lookup client (dns server).
            // NXDOMAIN is not a real failure like a timeout - flag it via IsNotFound so callers can
            // treat it as "no record". SERVFAIL/REFUSED are not included here: for a forward lookup
            // they mean the resolver actually failed or refused the query, not "record does not exist".
            if (result.HasError)
                return new DNSClientResultIPAddress(result.HasError, result.ErrorMessage, $"{result.NameServer}")
                { IsNotFound = IsNotFoundResponseCode(result.Header.ResponseCode) };

            // Validate result because of https://github.com/BornToBeRoot/NETworkManager/issues/1934

View on GitHub (pinned to 2780d65469)