nats-io/nats-server · error

can not have a single nkey and a users array

Error message

can not have a single nkey and a users array

What it means

validateLeafNodeAuthOptions also rejects combining the single Nkey form with a Users array; if Users is non-empty and LeafNode.Nkey is set, this error is thrown. Like the user/pass variant, it exists because the two auth forms are mutually exclusive in leafnode configuration.

Source

Thrown at server/leafnode.go:379

		} 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_ {
		return warnings, nil
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Remove the single `nkey:` key and keep only the users array (users can themselves have nkey entries)
2. Or remove the users array and keep the single nkey
3. Validate with `nats-server -t` before restart

Example fix

// before
leafnodes {
  nkey: "ND..."
  users = [ { user: "a", pass: "p" } ]
}
// after
leafnodes {
  users = [ { nkey: "ND..." } ]
}

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

When it happens

Trigger: Options where o.LeafNode.Users has >= 1 entry and o.LeafNode.Nkey != "" — e.g. a leafnode block with both `nkey:` and a `users:` array; raised via validateLeafNode or parseLeafNodes.

Common situations: Adding a users array for multiple remotes while the original single nkey line was left behind; scripted config generation that always emits an nkey template plus dynamic users.

Related errors

• can not have a single user/pass 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/61f8b6d7829cb4f5. Report an issue: GitHub.