nats-io/nats-server · error

cannot find local account %q specified in leafnode %s

Error message

cannot find local account %q specified in leafnode %s

What it means

Leafnode validation in local (non-operator) config mode: checkAccountExists could not find the named account among configured accounts (users, authorization account, or a remote's local account), so the leafnode references an unknown account.

Source

Thrown at server/leafnode.go:249

	}

	// In local config mode, check that leafnode configuration refers to accounts that exist.
	if len(o.TrustedOperators) == 0 {
		accNames := map[string]struct{}{}
		for _, a := range o.Accounts {
			accNames[a.Name] = struct{}{}
		}
		// global account is always created
		accNames[DEFAULT_GLOBAL_ACCOUNT] = struct{}{}
		// in the context of leaf nodes, empty account means global account
		accNames[_EMPTY_] = struct{}{}
		// system account either exists or, if not disabled, will be created
		if o.SystemAccount == _EMPTY_ && !o.NoSystemAccount {
			accNames[DEFAULT_SYSTEM_ACCOUNT] = struct{}{}
		}
		checkAccountExists := func(accName string, cfgType string) error {
			if _, ok := accNames[accName]; !ok {
				return fmt.Errorf("cannot find local account %q specified in leafnode %s", accName, cfgType)
			}
			return nil
		}
		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
			}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Define the account in the accounts section
2. Fix the account name/key in the leafnode config
3. Remove the stale reference

When it happens

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