What causes "could not parse address string %q" in nats-io/nats-server?

Change the value to a plain 'host:port' string, e.g. '0.0.0.0:4222'.

could not parse address string %q

Error message

could not parse address string %q

What it means

This error comes from the address parsing helper in server/opts.go when a config value given as a string cannot be split into host and port by net.SplitHostPort. The library expects either an integer port or a 'host:port' string; a string in any other form is rejected with this message. Parsing aborts and the error is added to the config errors list.

Source

Thrown at server/opts.go:2004

}

// hostPort is simple struct to hold parsed listen/addr strings.
type hostPort struct {
	host string
	port int
}

// parseListen will parse listen option which is replacing host/net and port
func parseListen(v any) (*hostPort, error) {
	hp := &hostPort{}
	switch vv := v.(type) {
	// Only a port
	case int64:
		hp.port = int(vv)
	case string:
		host, port, err := net.SplitHostPort(vv)
		if err != nil {
			return nil, fmt.Errorf("could not parse address string %q", vv)
		}
		hp.port, err = strconv.Atoi(port)
		if err != nil {
			return nil, fmt.Errorf("could not parse port %q", port)
		}
		hp.host = host
	default:
		return nil, fmt.Errorf("expected port or host:port, got %T", vv)
	}
	return hp, nil
}

// parseCluster will parse the cluster config.
func parseCluster(v any, opts *Options, errors *[]error, warnings *[]error) error {
	var lt token
	defer convertPanicToErrorList(&lt, errors)

	tk, v := unwrapValue(v, &lt)

View on GitHub (pinned to 3a66a489d2)

Solutions

Change the value to a plain 'host:port' string, e.g. '0.0.0.0:4222'.
Use just an integer if you only want a port on the default host, e.g. 4222.
For IPv6, wrap the host in brackets with a port: '[::1]:4222'.
Print the exact offending string from the error (%q) and check for hidden whitespace or stray characters.

Example fix

// before
listen: nats://0.0.0.0:4222
// after
listen: 0.0.0.0:4222

Defensive patterns

Strategy: validation

Validate before calling

// validate the address string before writing it into the config
if _, _, err := net.SplitHostPort(addr); err != nil {
	return fmt.Errorf("invalid address %q: use host:port", addr)
}

Prevention

Always specify addresses as host:port, never bare host or full URL.
Bracket IPv6 hosts: [::1]:4222.
Trim whitespace/env output before inserting into config.

When it happens

Trigger: Setting listen/cluster/gateway/monitor addresses in the config as a string like 'nats://host', 'host:', 'localhost' (no port), or a malformed IPv6 literal, so SplitHostPort fails.

Common situations: Omitting the port ('listen: 0.0.0.0'); using a full URL instead of host:port ('listen: nats://0.0.0.0:4222'); unbalanced brackets in IPv6 literals; whitespace from templating.

Related errors

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