nats-io/nats-server · error

lookup for host %q: %v

Error message

lookup for host %q: %v

What it means

getRandomIP wraps a resolver.LookupHost failure while resolving a hostname used in a URL (route, gateway or leafnode remote): the DNS lookup for that host failed and the underlying resolver error is appended. The URL itself was already split into host:port; the fault is name resolution, not URL syntax.

Source

Thrown at server/server.go:4668

		s.Errorf("%s Accept error: %v", acceptName, err)
	}
	return tmpDelay
}

var errNoIPAvail = errors.New("no IP available")

func (s *Server) getRandomIP(resolver netResolver, url string, excludedAddresses map[string]struct{}) (string, error) {
	host, port, err := net.SplitHostPort(url)
	if err != nil {
		return "", err
	}
	// If already an IP, skip.
	if net.ParseIP(host) != nil {
		return url, nil
	}
	ips, err := resolver.LookupHost(context.Background(), host)
	if err != nil {
		return "", fmt.Errorf("lookup for host %q: %v", host, err)
	}
	if len(excludedAddresses) > 0 {
		for i := 0; i < len(ips); i++ {
			ip := ips[i]
			addr := net.JoinHostPort(ip, port)
			if _, excluded := excludedAddresses[addr]; excluded {
				if len(ips) == 1 {
					ips = nil
					break
				}
				ips[i] = ips[len(ips)-1]
				ips = ips[:len(ips)-1]
				i--
			}
		}
		if len(ips) == 0 {
			return "", errNoIPAvail
		}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Verify the hostname resolves (dig/nslookup) from the server host
2. Fix DNS configuration (/etc/resolv.conf, DNS server) or add an /etc/hosts entry
3. Use an IP address in the config to bypass DNS
4. Retry after transient DNS outages; the server retries solicitation

When it happens

Trigger: Thrown at server/server.go:4668 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/e039639447edd4c9. Report an issue: GitHub.