nsqio/nsq · error

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

Error message

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

What it means

Mirroring the lookupd check, nsqadmin validates every --nsqd-http-address with net.ResolveTCPAddr before serving (nsqadmin.go); failure aborts startup with 'failed to resolve --nsqd-http-address (%s) - %s'. Use this mode instead of lookupd mode only when you deliberately enumerate nsqd nodes directly; each address must be a resolvable host with a numeric TCP port (nsqd HTTP default 4151, not the TCP 4150).

Source

Thrown at nsqadmin/nsqadmin.go:94

				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
	}

	if opts.AllowConfigFromCIDR != "" {
		_, _, err := net.ParseCIDR(opts.AllowConfigFromCIDR)
		if err != nil {
			return nil, fmt.Errorf("failed to parse --allow-config-from-cidr (%s) - %s", opts.AllowConfigFromCIDR, err)
		}
	}

View on GitHub (pinned to 85cf10c09c)

Solutions

  1. Verify each entry from the nsqadmin host: 'getent hosts <host>' and 'nc -vz <host> 4151'.
  2. Normalize entries to host:port, numeric port 4151 (or your custom HTTP port), no scheme, no path.
  3. Pin stable DNS/IPs for nsqd nodes, or prefer --lookupd-http-address mode so discovery is dynamic.
  4. Re-run nsqadmin; repeat if another address in the list is flagged next.

Example fix

# before
nsqadmin --nsqd-http-address=nsqd1:4150
# failed to resolve --nsqd-http-address (nsqd1:4150) - ...  (4150 is the TCP port; also catches http:// prefixes)

# after
nsqadmin --nsqd-http-address=nsqd1:4151 --nsqd-http-address=nsqd2:4151
Defensive patterns

Strategy: validation

Validate before calling

for _, a := range nsqdAddrs {
    if _, err := net.ResolveTCPAddr("tcp", a); err != nil {
        return fmt.Errorf("bad --nsqd-http-address %q: %w (want host:4151)", a, err)
    }
}

Type guard

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

Try / catch

if err := runNsqadmin(args); err != nil && strings.Contains(err.Error(), "failed to resolve --nsqd-http-address") {
    return errors.New("check each entry is host:port (HTTP 4151), no http:// prefix; verify DNS from this host")
}

Prevention

When it happens

Trigger: A --nsqd-http-address entry lacking host:port form, containing a scheme prefix ('http://...'), a non-numeric port, an unresolvable hostname from nsqadmin's vantage point, or copied TCP-port values with the right hostname but intended for a different check. Only the first bad address is reported — fix and re-run if more remain.

Common situations: Browser-copied URLs with http:// pasted into the flag; short-lived cloud hostnames that expired before nsqadmin (re)start; mixed environments where nsqd runs in Docker with a bridge IP that changed; typos like 4150 (nsqd's TCP port) instead of 4151.

Related errors

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