nats-io/nats-server · error

operator mode does not allow specifying users in leafnode co

Error message

operator mode does not allow specifying users in leafnode config

What it means

Leafnode validation in operator mode: explicit users in the leafnodes authorization section are forbidden because in operator mode credentials/identities are governed by operator-signed JWTs, not static config users.

Source

Thrown at server/leafnode.go:271

		if err := checkAccountExists(o.LeafNode.Account, "authorization"); err != nil {
			return err
		}
		for _, lu := range o.LeafNode.Users {
			if lu.Account == nil { // means global account
				continue
			}
			if err := checkAccountExists(lu.Account.Name, "authorization"); err != nil {
				return err
			}
		}
		for _, r := range o.LeafNode.Remotes {
			if err := checkAccountExists(r.LocalAccount, "remote"); err != nil {
				return err
			}
		}
	} else {
		if len(o.LeafNode.Users) != 0 {
			return fmt.Errorf("operator mode does not allow specifying users in leafnode config")
		}
		for _, r := range o.LeafNode.Remotes {
			if !nkeys.IsValidPublicAccountKey(r.LocalAccount) {
				return fmt.Errorf(
					"operator mode requires account nkeys in remotes. " +
						"Please add an `account` key to each remote in your `leafnodes` section, to assign it to an account. " +
						"Each account value should be a 56 character public key, starting with the letter 'A'")
			}
		}
		if o.LeafNode.Port != 0 && o.LeafNode.Account != "" && !nkeys.IsValidPublicAccountKey(o.LeafNode.Account) {
			return fmt.Errorf("operator mode and non account nkeys are incompatible")
		}
	}

	// Validate compression settings
	if o.LeafNode.Compression.Mode != _EMPTY_ {
		if err := validateAndNormalizeCompressionOption(&o.LeafNode.Compression, CompressionS2Auto); err != nil {
			return err

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Remove the users block from leafnodes config
2. Rely on operator-signed credentials for leafnode auth
3. Switch to non-operator mode if static users are required

When it happens

Trigger: Thrown at server/leafnode.go:271 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/162c2339c8b6c986. Report an issue: GitHub.