{"record":{"id":"ebb0171547042005","repo":"dotnet/yarp","slug":"failed-to-resolve-host-hostname-see-nameof-e","errorCode":null,"errorMessage":"Failed to resolve host '{hostName}'. See {nameof(Exception.InnerException)} for details.","messagePattern":"Failed to resolve host '(.+?)'\\. See (.+?) for details\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/ReverseProxy/ServiceDiscovery/DnsDestinationResolver.cs","lineNumber":81,"sourceCode":"        string originalName,\n        DestinationConfig originalConfig,\n        CancellationToken cancellationToken)\n    {\n        var originalUri = new Uri(originalConfig.Address);\n        var originalHost = originalConfig.Host is { Length: > 0 } host ? host : originalUri.Authority;\n        var hostName = originalUri.DnsSafeHost;\n        IPAddress[] addresses;\n        try\n        {\n            addresses = options.AddressFamily switch\n            {\n                { } addressFamily => await Dns.GetHostAddressesAsync(hostName, addressFamily, cancellationToken).ConfigureAwait(false),\n                null => await Dns.GetHostAddressesAsync(hostName, cancellationToken).ConfigureAwait(false)\n            };\n        }\n        catch (Exception exception)\n        {\n            throw new InvalidOperationException($\"Failed to resolve host '{hostName}'. See {nameof(Exception.InnerException)} for details.\", exception);\n        }\n\n        var results = new List<(string Name, DestinationConfig Config)>(addresses.Length);\n        var uriBuilder = new UriBuilder(originalUri);\n        var healthUri = originalConfig.Health is { Length: > 0 } health ? new Uri(health) : null;\n        var healthUriBuilder = healthUri is { } ? new UriBuilder(healthUri) : null;\n        foreach (var address in addresses)\n        {\n            var addressString = address.ToString();\n            uriBuilder.Host = addressString;\n            var resolvedAddress = uriBuilder.Uri.ToString();\n            var healthAddress = originalConfig.Health;\n            if (healthUriBuilder is not null)\n            {\n                healthUriBuilder.Host = addressString;\n                healthAddress = healthUriBuilder.Uri.ToString();\n            }\n","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/dotnet/yarp/blob/bd11867bee7df522e7fd3effb08a9c85fd616908/src/ReverseProxy/ServiceDiscovery/DnsDestinationResolver.cs#L63-L99","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ncluster.Destinations[\"d1\"].Address = \"https://backend.svc.wrong-namespace/\";\n// after\ncluster.Destinations[\"d1\"].Address = \"https://backend.svc.cluster.local/\";","handlingStrategy":"retry","validationCode":"// Pre-flight check from the proxy host\ntry { await Dns.GetHostAddressesAsync(host); } catch { return false; /* not resolvable */ }","typeGuard":null,"tryCatchPattern":"try { await resolver.ResolveDestinationsAsync(...); }\ncatch (InvalidOperationException ex) when (ex.InnerException is not null)\n{\n    _logger.LogError(ex.InnerException, \"DNS resolve failed for destination\");\n    // fall back to stale cached addresses or fail the route\n}","preventionTips":["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."],"tags":["network","dns","service-discovery","runtime","yarp"],"backgroundTag":null,"analyzedSha":"bd11867bee7df522e7fd3effb08a9c85fd616908","analyzedAt":"2026-08-13T21:29:49.359Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}