nats-io/nats-server · error

expected port or host:port, got %T

Error message

expected port or host:port, got %T

What it means

The address parser accepts only int64 (a bare port) or string (host:port) config values; any other YAML/JSON type hits the default branch and produces this error including the Go type of the offending value. It tells you the config key for the address was provided as an unsupported type (bool, float, array, map, null).

Source

Thrown at server/opts.go:2012

// 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)
	cm, ok := v.(map[string]any)
	if !ok {
		return &configErr{tk, fmt.Sprintf("Expected map to define cluster, got %T", v)}
	}

	for mk, mv := range cm {
		// Again, unwrap token value if line check is required.
		tk, mv = unwrapValue(mv, &lt)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Quote the value to force a string: listen: "0.0.0.0:4222".
2. Remove a trailing .0 or decimals so YAML parses a plain integer, or quote it: "4222".
3. Replace arrays/maps/null with a single host:port string value.
4. Read the %T in the message (e.g. float64, bool, []interface {}) to identify exactly which type YAML produced and adjust.

Example fix

// before
listen: 4222.0
// after
listen: 4222

func isAddressValue(v any) bool {
	switch t := v.(type) {
	case int64:
		return t > 0 && t <= 65535
	case string:
		_, _, err := net.SplitHostPort(t)
		return err == nil
	}
	return false
}

When it happens

Trigger: Values like listen: true, listen: 4222.0 (parsed as float64), listen: [4222], or listen: null in the config file — anything not an integer or string.

Common situations: YAML interpreting 4222.0 as a float; inconsistent quoting; passing a list of addresses where one string is expected; empty value rendered as null by templating.

Related errors

• %v
• could not parse address string %q
• must be int64 or string
• ErrBadSigningAlgorithm
• mqtt authentication token not compatible with presence of us

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