nats-io/nats-server · critical

error resolving system account: %v

Error message

error resolving system account: %v

What it means

This error is returned by the NATS server while resolving the system account during startup. The server failed to look up or build the account referenced as the system account ('$SYS' or a configured system account), and the underlying resolution error is wrapped in this message. Without a resolvable system account, system-level services (internal client, sys account subscriptions) cannot start.

Source

Thrown at server/server.go:1453

		s.mu.Unlock()
		s.registerSystemImports(acc)
		s.mu.Lock()
	}

	// Set the system account if it was configured.
	// Otherwise create a default one.
	if opts.SystemAccount != _EMPTY_ {
		// Lock may be acquired in lookupAccount, so release to call lookupAccount.
		s.mu.Unlock()
		acc, err := s.lookupAccount(opts.SystemAccount)
		s.mu.Lock()
		if err == nil && s.sys != nil && acc != s.sys.account {
			// sys.account.clients (including internal client)/respmap/etc... are transferred separately
			s.sys.account = acc
			s.sysAcc.Store(acc)
		}
		if err != nil {
			return awcsti, fmt.Errorf("error resolving system account: %v", err)
		}

		// If we have defined a system account here check to see if its just us and the $G account.
		// We would do this to add user/pass to the system account. If this is the case add in
		// no-auth-user for $G.
		// Only do this if non-operator mode and we did not have an authorization block defined.
		if len(opts.TrustedOperators) == 0 && numAccounts == 2 && opts.NoAuthUser == _EMPTY_ && !opts.authBlockDefined {
			// If we come here from config reload, let's not recreate the fake user name otherwise
			// it will cause currently clients to be disconnected.
			uname := s.sysAccOnlyNoAuthUser
			if uname == _EMPTY_ {
				// Create a unique name so we do not collide.
				var b [8]byte
				rn := rand.Int63()
				for i, l := 0, rn; i < len(b); i++ {
					b[i] = digits[l%base]
					l /= base
				}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Verify the system account name resolves: ensure its JWT is in the resolver preload (`resolver_preload`) or fetchable from the resolver URL
2. Check resolver connectivity/logs (nslookup/curl the resolver URL) and fix network or URL configuration
3. In operator mode re-push the system account JWT with `nsc` and confirm it is signed by the operator key
4. Run with `-DV` trace logging and inspect the wrapped `%v` error for the root cause

Example fix

// before
resolver = URL(http://localhost:9090)
// after
resolver = URL(http://localhost:9090)
resolver_preload = {
  $SYS: "eyJ0eXAiOiJKV1Qi..."  # system account JWT available locally
}

// Before starting the server, confirm the system account is present in the resolver
import "github.com/nats-io/jwt/v2"
claims, err := jwt.DecodeAccountClaims(sysAccJWT)
if err != nil || claims.Subject != "$SYS" {
    log.Fatalf("system account JWT invalid: %v", err)
}

// Wrap startup and inspect the wrapped resolver error
if err := srv.Start(); err != nil {
    if strings.Contains(err.Error(), "error resolving system account") {
        log.Fatalf("fix resolver/preload for the system account: %v", err)
    }
    return err
}

When it happens

Trigger: Options specify a system account (s.opts.SystemAccount / system account name) whose account claims cannot be fetched from the account resolver (e.g. a URL resolver returns 404/timeout, or the account is not in a MEM/DIR resolver preload). The check `if err == nil && s.sys != nil && acc != s.sys.account` runs after lookupAccount; any resolver error surfaces here.

Common situations: Operator mode with a remote resolver whose JWT is missing or unsigned for the system account; typo in the system account name; resolver unreachable (network/DNS); system account JWT expired or deleted from a DIR resolver.

Related errors

• unable to register client OCSP verification
• no hostport specified
• error opening config file: %v
• error setting up pack request handling: %v
• error setting up list request handling: %v

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