What does net.LookupHost return, and how do you tell a nonexistent hostname from a resolver failure?

## What the function is `net.LookupHost` is the simplest name-resolution entry point in Go's standard library: ```go func LookupHost(host string) (addrs []string, err error) ``` Given a hostname it returns the addresses that name resolves to, each formatted as a string such as `93.184.216.34` or `2606:2800:220:1:248:1893:25c8:1946`. If you hand it something that is already an IP address literal, it returns that literal back unchanged without doing a query. It resolves the way the platform is configured to resolve — typically the hosts file first and then DNS, though that order is itself configurable — so a name in `/etc/hosts` will resolve even with no nameserver reachable. There are two closely related calls worth knowing. `net.LookupIP(host)` returns `[]net.IP` values instead of strings, which saves you re-parsing them. `net.Resolver` has method forms — `LookupHost(ctx, host)`, `LookupIPAddr(ctx, host)`, `LookupNetIP(ctx, network, host)` — and those take a `context.Context`, so they can be cancelled or given a deadline. The package-level functions are thin wrappers over `net.DefaultResolver` with a background context, which means **a package-level lookup cannot be cancelled**. In a server, prefer the resolver method with the request's context. ## The error is the interesting part A name that does not exist does not come back as an empty slice and a nil error. It comes back as an error. Every failure from these calls is a `*net.DNSError`: ```go type DNSError struct { Err string // description of the error Name string // name looked up Server string // server used IsTimeout bool IsTemporary bool IsNotFound bool } ``` The distinction that matters operationally is between *the name does not exist* and *I could not find out whether the name exists*. They call for opposite responses. A nonexistent name is usually a configuration bug — a typo, a service that was never registered, a missing search domain — and retrying it in a loop just burns queries. A timeout or a refused query is an infrastructure condition and retrying is exactly right. `IsNotFound` is the flag for the first case: the resolver got an authoritative answer that there are no addresses for this name. `IsTimeout` means no answer arrived in time. `IsTemporary` is the broader hint that the condition may clear on its own. ## Reaching the fields correctly Use `errors.As`, not a type assertion: ```go var dnsErr *net.DNSError if errors.As(err, &dnsErr) && dnsErr.IsNotFound { // permanent: do not retry } ``` A direct assertion `err.(*net.DNSError)` works only when the `*net.DNSError` is the outermost error. The moment the lookup happens somewhere deeper — inside a dial, inside a client call, inside your own wrapping with `fmt.Errorf("...: %w", err)` — the assertion fails while `errors.As` still finds it, because `errors.As` walks the whole unwrap chain. The other common mistake is string matching. Code like `strings.Contains(err.Error(), "no such host")` is fragile: the message text is not part of the API contract, and the wording differs between the two resolver implementations Go can use and between platforms. The boolean fields exist precisely so you do not have to do this. ## Practical shape A lookup wrapper in a real service usually looks like: call the resolver method with a context; on error, `errors.As` to `*net.DNSError`; classify into permanent (`IsNotFound`) versus retryable (`IsTimeout` or `IsTemporary`); log `Name` and `Server` so the on-call engineer can see which nameserver gave the answer; and surface a permanent failure loudly rather than retrying it forever. One subtlety about cancellation: when the lookup is being served by the C library rather than Go's own resolver, cancelling the context makes the Go call return promptly, but the underlying C call cannot be interrupted and finishes in its own time. Your code is unblocked; the work underneath is not.