What causes "failed to resolve --lookupd-http-address (%s) - %s" in nsqio/nsq?

Test from the nsqadmin host: 'nc -vz host 4161' or 'getent hosts host' — resolve the name or fix the typo.

failed to resolve --lookupd-http-address (%s) - %s

Error message

failed to resolve --lookupd-http-address (%s) - %s

What it means

At startup nsqadmin validates every address in --lookupd-http-address by calling net.ResolveTCPAddr on it (nsqadmin.go). If resolution fails — malformed host:port, unknown hostname, bad port literal — New aborts with 'failed to resolve --lookupd-http-address (%s) - %s' echoing the offending address and the resolver error. This is a pre-flight check: it catches typos and DNS problems before the web UI starts making requests.

Source

Thrown at nsqadmin/nsqadmin.go:87

		n.httpClientTLSConfig.Certificates = []tls.Certificate{cert}
	}
	if opts.HTTPClientTLSRootCAFile != "" {
		tlsCertPool := x509.NewCertPool()
		caCertFile, err := os.ReadFile(opts.HTTPClientTLSRootCAFile)
		if err != nil {
			return nil, fmt.Errorf("failed to read TLS root CA file %s - %s",
				opts.HTTPClientTLSRootCAFile, err)
		}
		if !tlsCertPool.AppendCertsFromPEM(caCertFile) {
			return nil, fmt.Errorf("failed to AppendCertsFromPEM %s", opts.HTTPClientTLSRootCAFile)
		}
		n.httpClientTLSConfig.RootCAs = tlsCertPool
	}

	for _, address := range opts.NSQLookupdHTTPAddresses {
		_, err := net.ResolveTCPAddr("tcp", address)
		if err != nil {
			return nil, fmt.Errorf("failed to resolve --lookupd-http-address (%s) - %s", address, err)
		}
	}

	for _, address := range opts.NSQDHTTPAddresses {
		_, err := net.ResolveTCPAddr("tcp", address)
		if err != nil {
			return nil, fmt.Errorf("failed to resolve --nsqd-http-address (%s) - %s", address, err)
		}
	}

	if opts.ProxyGraphite {
		url, err := url.Parse(opts.GraphiteURL)
		if err != nil {
			return nil, fmt.Errorf("failed to parse --graphite-url (%s) - %s", opts.GraphiteURL, err)
		}
		n.graphiteURL = url
	}

View on GitHub (pinned to 85cf10c09c)

Solutions

Test from the nsqadmin host: 'nc -vz host 4161' or 'getent hosts host' — resolve the name or fix the typo.
Use plain host:port with no scheme and a numeric port (default lookupd HTTP port is 4161), e.g. --lookupd-http-address=10.0.0.2:4161.
For container DNS issues, use the service IP/FQDN or fix the resolver; for IPv6 write [::1]:4161.
Restart nsqadmin once every listed address resolves.

Example fix

# before
nsqadmin --lookupd-http-address=http://lookupd:4161
# failed to resolve --lookupd-http-address (http://lookupd:4161) - address http://lookupd:4161: too many colons

# after
nsqadmin --lookupd-http-address=lookupd.internal:4161
getent hosts lookupd.internal   # verify DNS from the nsqadmin host first

Defensive patterns

Strategy: validation

Validate before calling

// pre-start: validate every lookupd address exactly like nsqadmin does
for _, a := range lookupdAddrs {
    if _, err := net.ResolveTCPAddr("tcp", a); err != nil {
        return fmt.Errorf("bad --lookupd-http-address %q: %w (want host:port, no scheme)", a, err)
    }
}

Type guard

func isHostPort(s string) bool {
    _, err := net.ResolveTCPAddr("tcp", s)
    return err == nil
}

Try / catch

// config loaders: surface a hint for the common scheme-prefix mistake
if err := runNsqadmin(args); err != nil && strings.Contains(err.Error(), "failed to resolve --lookupd-http-address") {
    return errors.New("strip http:// and use host:4161 for every lookupd address")
}

Prevention

Never paste browser URLs into address flags; strip schemes and paths.
Validate addresses from the exact host/network where nsqadmin runs.
Prefer lookupd mode over enumerating nodes when DNS is dynamic.

When it happens

Trigger: Passing an address without a port ('lookupd' alone fails; the form must be host:port), a non-numeric port ('nsqlookupd:http'), a hostname not resolvable from the nsqadmin host, or stray whitespace/scheme prefixes like 'http://host:4161' (the scheme is not part of a TCP address and ResolveTCPAddr rejects it).

Common situations: DNS entries existing in one environment but not where nsqadmin runs (k8s service names outside the cluster, split-horizon DNS); compose service names used on bare metal; copy-paste from browser URLs leaving 'http://' on the address; IPv6 addresses written without brackets.

Related errors

AI-assisted analysis of nsqio/nsq@85cf10c09c (2026-08-16). Data as JSON: /api/errors/26551c02b151ae90. Report an issue: GitHub.