nats-io/nats-server · error

no hostport specified

Error message

no hostport specified

What it means

parseHostPort in server/util.go validates and splits a "host:port" string. When it receives an empty or missing hostport value it returns the sentinel error "no hostport specified" with port -1. The library treats this as a configuration error because callers cannot form a valid listen/advertise address without it.

Source

Thrown at server/util.go:174

	if hostPort != "" {
		host, sPort, err := net.SplitHostPort(hostPort)
		if ae, ok := err.(*net.AddrError); ok && strings.Contains(ae.Err, "missing port") {
			// try appending the current port
			host, sPort, err = net.SplitHostPort(fmt.Sprintf("%s:%d", hostPort, defaultPort))
		}
		if err != nil {
			return "", -1, err
		}
		port, err = strconv.Atoi(strings.TrimSpace(sPort))
		if err != nil {
			return "", -1, err
		}
		if port == 0 || port == -1 {
			port = defaultPort
		}
		return strings.TrimSpace(host), port, nil
	}
	return "", -1, errors.New("no hostport specified")
}

// Returns true if URL u1 represents the same URL than u2,
// false otherwise.
func urlsAreEqual(u1, u2 *url.URL) bool {
	return reflect.DeepEqual(u1, u2)
}

// comma produces a string form of the given number in base 10 with
// commas after every three orders of magnitude.
//
// e.g. comma(834142) -> 834,142
//
// This function was copied from the github.com/dustin/go-humanize
// package (MIT License) and is Copyright Dustin Sallings <dustin@spy.net>
func comma(v int64) string {
	sign := ""

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set a valid host value in the relevant config block (e.g. host: "0.0.0.0" or the advertised hostname) instead of leaving it empty
2. Check environment variables or templates that substitute the host — an unset variable yields an empty hostport
3. If building Options in code, ensure options.Host (or the block's Host field) is non-empty before calling server.New/Parse
4. For cluster/route URLs, use full `host:port` URLs such as nats-route://host:4222

Example fix

// before (server.conf)
cluster {
  name: c1
  host: ""
  port: 4222
}
// after
cluster {
  name: c1
  host: "0.0.0.0"
  port: 4222
}

func validateHostPort(hp string) error {
    if strings.TrimSpace(hp) == "" {
        return errors.New("hostport must be non-empty, e.g. 0.0.0.0:4222")
    }
    if _, _, err := net.SplitHostPort(hp); err != nil {
        return fmt.Errorf("invalid hostport %q: %w", hp, err)
    }
    return nil
}

When it happens

Trigger: Calling setGatewayInfoHostPort, setLeafNodeInfoHostPortAndIP, setRouteInfoHostPortAndIP, setInfoHostPort, diffOptions or validateClusterOpts with an empty string or a value without a host part (e.g. `":4222"`-style values missing entirely, or an empty option) — the underlying host portion is blank so parseHostPort bails out before defaulting the port.

Common situations: NATS server config with an empty `host`/`listen` value in gateway, leafnode, cluster or route blocks; environment-variable interpolation producing an empty string; programmatic option construction (server.Options) leaving Host empty while a port-only URL was expected to include a host.

Related errors

• unable to register client OCSP verification
• error opening config file: %v
• mqtt requires JetStream to be enabled if running in standalo
• unable to plug TLS verify connection, config is nil
• OCSP peer verification for client connections requires TLS v

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