HttpClient: 'No such host is known' (SocketException 11001)

HttpRequestException: No such host is known. (patients-api.invalid:15801) with an inner SocketException (11001) means the host name in your URL could not be resolved to an address. Check the host part of the URL, the name in brackets at the end of the message, and correct it.

The message names the host and port it tried, so compare that name with the one your server really answers on, correct it where the base address is set, and run again. In the test, changing only the host name turned the exception into a 200.

The error

PS ...\Cli> dotnet run --no-build -- dns
HttpRequestError: NameResolutionError
Inner: System.Net.Sockets.SocketException
SocketErrorCode: HostNotFound, ErrorCode: 11001
Unhandled exception. System.Net.Http.HttpRequestException: No such host is known. (patients-api.invalid:15801)
 ---> System.Net.Sockets.SocketException (11001): No such host is known.
   at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.ThrowException(SocketError error, CancellationToken cancellationToken)
   at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.System.Threading.Tasks.Sources.IValueTaskSource.GetResult(Int16 token)
   at System.Net.Http.HttpConnectionPool.ConnectToTcpHostAsync(String host, Int32 port, HttpRequestMessage initialRequest, Boolean async, CancellationToken cancellationToken)
   --- End of inner exception stack trace ---
...
   at Program.<Main>$(String[] args) in ...\Cli\Program.cs:line 83
   at Program.<Main>(String[] args)

The first three lines were printed by the test's own catch block before it rethrew. The code:

using var http = new HttpClient { BaseAddress = new Uri("http://patients-api.invalid:15801/api/v1/") };
try
{
    Console.WriteLine(await http.GetStringAsync("patients"));
}
catch (HttpRequestException ex)
{
    Console.WriteLine("HttpRequestError: " + ex.HttpRequestError);
    Console.WriteLine("Inner: " + ex.InnerException?.GetType().FullName);
    if (ex.InnerException is System.Net.Sockets.SocketException se)
        Console.WriteLine($"SocketErrorCode: {se.SocketErrorCode}, ErrorCode: {se.ErrorCode}");
    throw;
}

Why it happens

Before HttpClient can open a TCP connection it needs an IP address for the host name. The name patients-api.invalid uses the reserved .invalid top-level domain, so it resolves nowhere, and the lookup failed with Windows socket error 11001, reported as SocketErrorCode.HostNotFound. The stack trace stops in ConnectToTcpHostAsync, and the exception's HttpRequestError property says NameResolutionError.

That property is the useful part in code: a catch block can read ex.HttpRequestError, as the test does, and log a clear "check the host name" message when it is NameResolutionError, instead of matching on the exception text.

The fix

Use a host name that resolves. With the base address pointed at the running test server:

using var http = new HttpClient { BaseAddress = new Uri("http://127.0.0.1:15801/api/v1/") };
var text = await http.GetStringAsync("patients");
Console.WriteLine(text);

PS ...\Cli> dotnet run --no-build -- fixed
200 from /api/v1/patients: Maria Garcia, David Chen

Only the host changed in the base address; the path, /api/v1/, and the port, 15801, stayed the same. If your base address comes from configuration, correct the value there and the code needs no change.

How it was reproduced

A console app (dotnet new console, no packages) on .NET SDK 10.0.403 set BaseAddress to http://patients-api.invalid:15801/api/v1/ and called GetStringAsync("patients"). The fixed run used http://127.0.0.1:15801/api/v1/, where a minimal API (dotnet new web) was running for the test.

Frequently asked

What does SocketException 11001 No such host is known mean?

The host name in the URL could not be resolved to an IP address. In the test the inner SocketException had SocketErrorCode HostNotFound and ErrorCode 11001.

How do I detect a DNS failure from HttpClient in C#?

Catch HttpRequestException and check its HttpRequestError property. For the unresolvable host in the test it was NameResolutionError.

Which host does HttpClient say it could not find?

The message ends with the host and port in brackets, for example (patients-api.invalid:15801). Compare that with the address your server answers on.

More decoded errors in the Fixes category. For the error a client gets from a reachable machine with nothing on the port, see No connection could be made because the target machine actively refused it.