What causes "account exists" in nats-io/nats-server?

Look up the existing account first (s.LookupAccount) and reuse it instead of registering a new one

account exists

Error message

account exists

What it means

ErrAccountExists is returned when registering an account that is already present in the server's account map. server.go:1774 (account registration) returns it if s.accounts already holds the name; server.go:1848 returns it from the system-account setup if the system account is registered twice. It protects against duplicate Account creation/registration.

Source

Thrown at server/errors.go:102

	// ErrClientConnectedToLeafNodePort represents an error condition when a client
	// attempted to connect to the leaf node listen port.
	ErrClientConnectedToLeafNodePort = errors.New("attempted to connect to leaf node port")

	// ErrLeafNodeHasSameClusterName represents an error condition when a leafnode is a cluster
	// and it has the same cluster name as the hub cluster.
	ErrLeafNodeHasSameClusterName = errors.New("remote leafnode has same cluster name")

	// ErrLeafNodeDisabled is when we disable leafnodes.
	ErrLeafNodeDisabled = errors.New("leafnodes disabled")

	// ErrConnectedToWrongPort represents an error condition when a connection is attempted
	// to the wrong listen port (for instance a LeafNode to a client port, etc...)
	ErrConnectedToWrongPort = errors.New("attempted to connect to wrong port")

	// ErrAccountExists is returned when an account is attempted to be registered
	// but already exists.
	ErrAccountExists = errors.New("account exists")

	// ErrBadAccount represents a malformed or incorrect account.
	ErrBadAccount = errors.New("bad account")

	// ErrReservedAccount represents a reserved account that can not be created.
	ErrReservedAccount = errors.New("reserved account")

	// ErrMissingAccount is returned when an account does not exist.
	ErrMissingAccount = errors.New("account missing")

	// ErrMissingService is returned when an account does not have an exported service.
	ErrMissingService = errors.New("service missing")

	// ErrBadServiceType is returned when latency tracking is being applied to non-singleton response types.
	ErrBadServiceType = errors.New("bad service response type")

	// ErrBadSampling is returned when the sampling for latency tracking is not 1 >= sample <= 100.
	ErrBadSampling = errors.New("bad sampling percentage, should be 1-100")

View on GitHub (pinned to 3a66a489d2)

Solutions

Look up the existing account first (s.LookupAccount) and reuse it instead of registering a new one
Skip registration if the account name is already known
Fix double-initialization so setup code runs once (sync.Once or guard flag)

Example fix

// before
if _, err := s.RegisterAccount(acc); err != nil { return err } // may be ErrAccountExists
// after
if existing, _ := s.LookupAccount(acc.Name); existing == nil {
    if _, err := s.RegisterAccount(acc); err != nil { return err }
}

Defensive patterns

Strategy: try-catch

Validate before calling

if existing, _ := s.LookupAccount(name); existing != nil { return existing } // skip registration

Try / catch

acc, err := s.RegisterAccount(acc)
if errors.Is(err, server.ErrAccountExists) {
    acc, err = s.LookupAccount(name) // reuse existing
}

Prevention

Guard registration with a prior LookupAccount
Initialize accounts once (sync.Once / single bootstrap path)
Watch for races: register under a lock or idempotent helper

When it happens

Trigger: Calling s.RegisterAccount(acc) twice for the same account name; setting up the system account ($SYS) when it was already registered; resolver code re-adding an account fetched concurrently.

Common situations: Double-initialization paths in embedded-NATS applications (calling RegisterAccount from both bootstrap and reload); race between two goroutines registering the same account; tests reusing a server instance without resetting state.

Related errors

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