{"record":{"id":"409b721988bf9096","repo":"nats-io/nats-server","slug":"error-resolving-system-account-v","errorCode":null,"errorMessage":"error resolving system account: %v","messagePattern":"error resolving system account: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/server.go","lineNumber":1453,"sourceCode":"\t\ts.mu.Unlock()\n\t\ts.registerSystemImports(acc)\n\t\ts.mu.Lock()\n\t}\n\n\t// Set the system account if it was configured.\n\t// Otherwise create a default one.\n\tif opts.SystemAccount != _EMPTY_ {\n\t\t// Lock may be acquired in lookupAccount, so release to call lookupAccount.\n\t\ts.mu.Unlock()\n\t\tacc, err := s.lookupAccount(opts.SystemAccount)\n\t\ts.mu.Lock()\n\t\tif err == nil && s.sys != nil && acc != s.sys.account {\n\t\t\t// sys.account.clients (including internal client)/respmap/etc... are transferred separately\n\t\t\ts.sys.account = acc\n\t\t\ts.sysAcc.Store(acc)\n\t\t}\n\t\tif err != nil {\n\t\t\treturn awcsti, fmt.Errorf(\"error resolving system account: %v\", err)\n\t\t}\n\n\t\t// If we have defined a system account here check to see if its just us and the $G account.\n\t\t// We would do this to add user/pass to the system account. If this is the case add in\n\t\t// no-auth-user for $G.\n\t\t// Only do this if non-operator mode and we did not have an authorization block defined.\n\t\tif len(opts.TrustedOperators) == 0 && numAccounts == 2 && opts.NoAuthUser == _EMPTY_ && !opts.authBlockDefined {\n\t\t\t// If we come here from config reload, let's not recreate the fake user name otherwise\n\t\t\t// it will cause currently clients to be disconnected.\n\t\t\tuname := s.sysAccOnlyNoAuthUser\n\t\t\tif uname == _EMPTY_ {\n\t\t\t\t// Create a unique name so we do not collide.\n\t\t\t\tvar b [8]byte\n\t\t\t\trn := rand.Int63()\n\t\t\t\tfor i, l := 0, rn; i < len(b); i++ {\n\t\t\t\t\tb[i] = digits[l%base]\n\t\t\t\t\tl /= base\n\t\t\t\t}","sourceCodeStart":1435,"sourceCodeEnd":1471,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/server.go#L1435-L1471","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the system account name resolves: ensure its JWT is in the resolver preload (`resolver_preload`) or fetchable from the resolver URL","Check resolver connectivity/logs (nslookup/curl the resolver URL) and fix network or URL configuration","In operator mode re-push the system account JWT with `nsc` and confirm it is signed by the operator key","Run with `-DV` trace logging and inspect the wrapped `%v` error for the root cause"],"exampleFix":"// before\nresolver = URL(http://localhost:9090)\n// after\nresolver = URL(http://localhost:9090)\nresolver_preload = {\n  $SYS: \"eyJ0eXAiOiJKV1Qi...\"  # system account JWT available locally\n}","handlingStrategy":"validation","validationCode":"// Before starting the server, confirm the system account is present in the resolver\nimport \"github.com/nats-io/jwt/v2\"\nclaims, err := jwt.DecodeAccountClaims(sysAccJWT)\nif err != nil || claims.Subject != \"$SYS\" {\n    log.Fatalf(\"system account JWT invalid: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"// Wrap startup and inspect the wrapped resolver error\nif err := srv.Start(); err != nil {\n    if strings.Contains(err.Error(), \"error resolving system account\") {\n        log.Fatalf(\"fix resolver/preload for the system account: %v\", err)\n    }\n    return err\n}","preventionTips":["Always include the system account JWT in resolver_preload when using MEM/DIR resolvers","Test the resolver URL with curl before deploying operator-mode configs","Re-push system account JWTs after operator key rotation","Run `nsc accounts report` to confirm the system account exists and is signed"],"tags":["nats-server","system-account","resolver","startup"],"backgroundTag":"account-resolution-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}