nats-io/nats-server · error

system account not setup

Error message

system account not setup

What it means

ErrNoSysAccount is returned when an operation requires the internal system account but none is set up on the server. Callers like account initialization (server/accounts.go:1291) and JetStream consumer/API helpers (server/consumer.go:1977) check `EventsEnabled()` (i.e., the system account and events are active) and return this sentinel when not. The message text is "system account not setup".

Source

Thrown at server/errors.go:169

	// ErrCycleSearchDepth is returned when we have exceeded our maximum search depth..
	ErrCycleSearchDepth = errors.New("search cycle depth exhausted")

	// ErrClientOrRouteConnectedToGatewayPort represents an error condition when
	// a client or route attempted to connect to the Gateway port.
	ErrClientOrRouteConnectedToGatewayPort = errors.New("attempted to connect to gateway port")

	// ErrWrongGateway represents an error condition when a server receives a connect
	// request from a remote Gateway with a destination name that does not match the server's
	// Gateway's name.
	ErrWrongGateway = errors.New("wrong gateway")

	// ErrGatewayNameHasSpaces signals that the gateway name contains spaces, which is not allowed.
	ErrGatewayNameHasSpaces = errors.New("gateway name cannot contain spaces")

	// ErrNoSysAccount is returned when an attempt to publish or subscribe is made
	// when there is no internal system account defined.
	ErrNoSysAccount = errors.New("system account not setup")

	// ErrRevocation is returned when a credential has been revoked.
	ErrRevocation = errors.New("credentials have been revoked")

	// ErrServerNotRunning is used to signal an error that a server is not running.
	ErrServerNotRunning = errors.New("server is not running")

	// ErrServerNameHasSpaces signals that the server name contains spaces, which is not allowed.
	ErrServerNameHasSpaces = errors.New("server name cannot contain spaces")

	// ErrBadMsgHeader signals the parser detected a bad message header
	ErrBadMsgHeader = errors.New("bad message header detected")

	// ErrMsgHeadersNotSupported signals the parser detected a message header
	// but they are not supported on this server.
	ErrMsgHeadersNotSupported = errors.New("message headers not supported")

	// ErrNoRespondersRequiresHeaders signals that a client needs to have headers

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Configure a system account: add `system_account: <SYS_ACCOUNT_PUBKEY>` to the server config (typically from an operator-mode resolver setup).
  2. Create the system account JWT if using operator/resolver mode (`nsc add account --name SYS` and push it).
  3. For embedded/test servers, set the system account programmatically via options before starting.
  4. Alternatively, disable the dependent feature (e.g. JetStream account monitoring) if no system account is intended.

Example fix

// before: server.conf without system account
// after
// system_account: ADMBQSNVSE2TZTPNBSWXWFOTWU5GHOCQMX4BPH2QKJKBXU7NZ6HSYOWC
Defensive patterns

Strategy: validation

Validate before calling

// Before using features that need the system account, verify it is configured:
// nats server info  -> check system account fields, or in config ensure
// `system_account` is present and the account JWT exists on the resolver.

Try / catch

if _, err := js.AccountInfo(); err != nil {
    if errors.Is(err, ErrNoSysAccount) {
        // disable dependent features or configure the system account
    }
}

Prevention

When it happens

Trigger: Publishing/subscribing on behalf of the system account when the server has no `system_account` configured; requesting JetStream account info / consumer APIs that rely on internal system requests while events are disabled; single-node dev servers started without a system account.

Common situations: Running a server without `system_account` in config but enabling features (JetStream monitoring, account activity) that need it; embedded servers used in tests without system account setup; mixed clusters where some nodes lack the system account config.

Related errors

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