nats-io/nats-server · error

invalid Cluster.Advertise value of %s, err=%v

Error message

invalid Cluster.Advertise value of %s, err=%v

What it means

During a config reload, validateClusterOpts parses the new cluster.advertise string with parseHostPort(advertise, 0) and fails when it is not a valid host[:port]. This is a syntax check on the operator-supplied advertise string (bad hostname characters, malformed port, etc.), surfaced with the underlying parse error (%v).

Source

Thrown at server/reload.go:2793

	}
	s.mu.Unlock()
}

// validateClusterOpts ensures the new ClusterOpts does not change some of the
// fields that do not support reload.
func validateClusterOpts(old, new ClusterOpts) error {
	if old.Host != new.Host {
		return fmt.Errorf("config reload not supported for cluster host: old=%s, new=%s",
			old.Host, new.Host)
	}
	if old.Port != new.Port {
		return fmt.Errorf("config reload not supported for cluster port: old=%d, new=%d",
			old.Port, new.Port)
	}
	// Validate Cluster.Advertise syntax
	if new.Advertise != "" {
		if _, _, err := parseHostPort(new.Advertise, 0); err != nil {
			return fmt.Errorf("invalid Cluster.Advertise value of %s, err=%v", new.Advertise, err)
		}
	}
	return nil
}

// diffRoutes diffs the old routes and the new routes and returns the ones that
// should be added and removed from the server.
func diffRoutes(old, new []*url.URL) (add, remove []*url.URL) {
	// Find routes to remove.
removeLoop:
	for _, oldRoute := range old {
		for _, newRoute := range new {
			if urlsAreEqual(oldRoute, newRoute) {
				continue removeLoop
			}
		}
		remove = append(remove, oldRoute)
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Correct cluster.advertise to a valid host or host:port string (e.g. 'nats.example.com:6222')
2. Remove cluster.advertise if the real client/host address should be used
3. Check for stray whitespace, scheme prefixes (http://) or non-numeric ports in the value

When it happens

Trigger: Thrown at server/reload.go:2793 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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