dotnet/yarp · error · InvalidOperationException

Failed to resolve host '{hostName}'. See {nameof(Exception.I

Error message

Failed to resolve host '{hostName}'. See {nameof(Exception.InnerException)} for details.

What it means

Thrown by DnsDestinationResolver when `Dns.GetHostAddressesAsync` raises any exception (DNS failure, NXDOMAIN, no network, socket error). The original exception is wrapped as InnerException of an InvalidOperationException so callers see a single, descriptive failure while preserving the root cause.

Source

Thrown at src/ReverseProxy/ServiceDiscovery/DnsDestinationResolver.cs:81

        string originalName,
        DestinationConfig originalConfig,
        CancellationToken cancellationToken)
    {
        var originalUri = new Uri(originalConfig.Address);
        var originalHost = originalConfig.Host is { Length: > 0 } host ? host : originalUri.Authority;
        var hostName = originalUri.DnsSafeHost;
        IPAddress[] addresses;
        try
        {
            addresses = options.AddressFamily switch
            {
                { } addressFamily => await Dns.GetHostAddressesAsync(hostName, addressFamily, cancellationToken).ConfigureAwait(false),
                null => await Dns.GetHostAddressesAsync(hostName, cancellationToken).ConfigureAwait(false)
            };
        }
        catch (Exception exception)
        {
            throw new InvalidOperationException($"Failed to resolve host '{hostName}'. See {nameof(Exception.InnerException)} for details.", exception);
        }

        var results = new List<(string Name, DestinationConfig Config)>(addresses.Length);
        var uriBuilder = new UriBuilder(originalUri);
        var healthUri = originalConfig.Health is { Length: > 0 } health ? new Uri(health) : null;
        var healthUriBuilder = healthUri is { } ? new UriBuilder(healthUri) : null;
        foreach (var address in addresses)
        {
            var addressString = address.ToString();
            uriBuilder.Host = addressString;
            var resolvedAddress = uriBuilder.Uri.ToString();
            var healthAddress = originalConfig.Health;
            if (healthUriBuilder is not null)
            {
                healthUriBuilder.Host = addressString;
                healthAddress = healthUriBuilder.Uri.ToString();
            }

View on GitHub (pinned to bd11867bee)

Solutions

Verify the host resolves from the proxy host: `dotnet run` of `Dns.GetHostAddressesAsync(host)` or `nslookup <host>`.
Correct the destination address in cluster config.
If forcing an address family, ensure records of that family exist, or set AddressFamily to null for any-family resolution.
Inspect `ex.InnerException` for the real socket/DNS error to pinpoint NXDOMAIN vs timeout vs refused.
For service discovery, ensure the service registry (Consul, Kubernetes, etc.) is reachable and the name is registered.

Example fix

// before
cluster.Destinations["d1"].Address = "https://backend.svc.wrong-namespace/";
// after
cluster.Destinations["d1"].Address = "https://backend.svc.cluster.local/";

Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight check from the proxy host
try { await Dns.GetHostAddressesAsync(host); } catch { return false; /* not resolvable */ }

Try / catch

try { await resolver.ResolveDestinationsAsync(...); }
catch (InvalidOperationException ex) when (ex.InnerException is not null)
{
    _logger.LogError(ex.InnerException, "DNS resolve failed for destination");
    // fall back to stale cached addresses or fail the route
}

Prevention

Smoke-test destination hosts with nslookup/dig from the proxy host during deploy.
Pin AddressFamily only when you know the records exist; prefer null for any-family.
Cache last-known-good resolved addresses so transient DNS failures degrade gracefully.
Monitor DNS resolution latency and failure rates for cluster destinations.

When it happens

Trigger: YARP resolves a cluster destination whose host is not resolvable: misconfigured host name, transient DNS outage, wrong address family (forced IPv6 with no AAAA records), or a host that only resolves on an internal network not reachable from the proxy host.

Common situations: Destination address uses a service DNS name not registered in the proxy's environment. Forcing `AddressFamily` to InterNetworkV6 against an IPv4-only host. Air-gapped/dev environment lacking DNS. Recently changed/removed DNS record. Typo in the destination URL host.

Related errors

AI-assisted analysis of dotnet/yarp@bd11867bee (2026-08-13). Data as JSON: /api/errors/ebb0171547042005. Report an issue: GitHub.