nats-io/nats-server · error

expected cluster password to be set

Error message

expected cluster password to be set

What it means

Parsing a cluster URL from options: the URL carries a username but no password component (clusterURL.User.Password() returned false), and cluster auth requires both or neither. The userinfo portion of the cluster:// URL is the input at fault.

Source

Thrown at server/opts.go:6546

		return err
	}
	h, p, err := net.SplitHostPort(clusterURL.Host)
	if err != nil {
		return err
	}
	if wantsRandom {
		p = "-1"
	}
	opts.Cluster.Host = h
	_, err = fmt.Sscan(p, &opts.Cluster.Port)
	if err != nil {
		return err
	}

	if clusterURL.User != nil {
		pass, hasPassword := clusterURL.User.Password()
		if !hasPassword {
			return errors.New("expected cluster password to be set")
		}
		opts.Cluster.Password = pass

		user := clusterURL.User.Username()
		opts.Cluster.Username = user
	} else {
		// Since we override from flag and there is no user/pwd, make
		// sure we clear what we may have gotten from config file.
		opts.Cluster.Username = _EMPTY_
		opts.Cluster.Password = _EMPTY_
	}

	return nil
}

func processSignal(signal string) error {
	var (
		pid           string

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add the password to the URL: cluster://user:pass@host:port
2. Remove the userinfo entirely if cluster auth is not used
3. Check for URL-encoding mistakes that drop or mangle the password

When it happens

Trigger: Thrown at server/opts.go:6546 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/7dfa21896ff642e4. Report an issue: GitHub.