nats-io/nats-server · error

can not have a single user/pass and a users array

Error message

can not have a single user/pass and a users array

What it means

validateLeafNodeAuthOptions enforces that leaf node authorization uses either the single Username/Password form or the Users array, not both. If Users is non-empty and LeafNode.Username is also set, configuration is ambiguous, so this error is thrown during validation (via validateLeafNode or parseLeafNodes).

Source

Thrown at server/leafnode.go:376

	if ok, err := versionAtLeastCheckError(mv, 2, 8, 0); !ok || err != nil {
		if err != nil {
			return fmt.Errorf("invalid leafnode's minimum version: %v", err)
		} else {
			return fmt.Errorf("the minimum version should be at least 2.8.0")
		}
	}
	return nil
}

// Used to validate user names in LeafNode configuration.
// - rejects mix of single and multiple users.
// - rejects duplicate user names.
func validateLeafNodeAuthOptions(o *Options) error {
	if len(o.LeafNode.Users) == 0 {
		return nil
	}
	if o.LeafNode.Username != _EMPTY_ {
		return fmt.Errorf("can not have a single user/pass and a users array")
	}
	if o.LeafNode.Nkey != _EMPTY_ {
		return fmt.Errorf("can not have a single nkey and a users array")
	}
	users := map[string]struct{}{}
	for _, u := range o.LeafNode.Users {
		if _, exists := users[u.Username]; exists {
			return fmt.Errorf("duplicate user %q detected in leafnode authorization", u.Username)
		}
		users[u.Username] = struct{}{}
	}
	return nil
}

func validateLeafNodeProxyOptions(remote *RemoteLeafOpts) ([]string, error) {
	var warnings []string

	if remote.Proxy.URL == _EMPTY_ {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Remove the single `user`/`pass` keys and keep only the users array
2. Or remove the users array and keep the single user/pass
3. Re-run `nats-server -t` (config test) to confirm validation passes

Example fix

// before
leafnodes {
  user: "leaf"
  pass: "secret"
  users = [ { user: "a", pass: "p1" }, { user: "b", pass: "p2" } ]
}
// after
leafnodes {
  users = [ { user: "a", pass: "p1" }, { user: "b", pass: "p2" } ]
}

if len(cfg.LeafNodes.Users) > 0 && cfg.LeafNodes.Username != "" {
  return errors.New("use either single user/pass or users array, not both")
}

When it happens

Trigger: Options where o.LeafNode.Users has >= 1 entry and o.LeafNode.Username != "" — e.g. config with both `user:`/`pass:` and a `users:` array under the leafnode block; triggered by NewServer/Validate or leafnode config parsing.

Common situations: Merging an old single-user leafnode auth block with a newer users array during config refactors; automation tools appending a users array while leaving legacy user/pass keys in place.

Related errors

• can not have a single nkey and a users array
• duplicate user %q detected in leafnode authorization
• remote leaf node URL %q cannot be used in FIPS-140 mode when
• leaf nodes and gateways (both being defined) require a syste
• leafnode: %v

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