{"record":{"id":"7818cb0dd39f11f3","repo":"nats-io/nats-server","slug":"setting-up-internal-jetstream-subscriptions-failed","errorCode":null,"errorMessage":"setting up internal jetstream subscriptions failed: %v","messagePattern":"setting up internal jetstream subscriptions failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream.go","lineNumber":510,"sourceCode":"\ts.Noticef(\"  Max Storage:     %s\", friendlyBytes(cfg.MaxStore))\n\ts.Noticef(\"  Store Directory: \\\"%s\\\"\", cfg.StoreDir)\n\tif cfg.Domain != _EMPTY_ {\n\t\ts.Noticef(\"  Domain:          %s\", cfg.Domain)\n\t}\n\n\tif ek := opts.JetStreamKey; ek != _EMPTY_ {\n\t\ts.Noticef(\"  Encryption:      %s\", opts.JetStreamCipher)\n\t}\n\tif opts.JetStreamTpm.KeysFile != _EMPTY_ {\n\t\ts.Noticef(\"  TPM File:        %q, Pcr: %d\", opts.JetStreamTpm.KeysFile,\n\t\t\topts.JetStreamTpm.Pcr)\n\t}\n\ts.Noticef(\"  API Level:       %d\", JSApiLevel)\n\ts.Noticef(\"-------------------------------------------\")\n\n\t// Setup our internal subscriptions.\n\tif err := s.setJetStreamExportSubs(); err != nil {\n\t\treturn fmt.Errorf(\"setting up internal jetstream subscriptions failed: %v\", err)\n\t}\n\n\t// Setup our internal system exports.\n\ts.Debugf(\"  Exports:\")\n\ts.Debugf(\"     %s\", jsAllAPI)\n\ts.setupJetStreamExports()\n\n\tstandAlone, canExtend := s.standAloneMode(), s.canExtendOtherDomain()\n\tif standAlone && canExtend && s.getOpts().JetStreamExtHint != jsWillExtend {\n\t\tcanExtend = false\n\t\ts.Noticef(\"Standalone server started in clustered mode do not support extending domains\")\n\t\ts.Noticef(`Manually disable standalone mode by setting the JetStream Option \"extension_hint: %s\"`, jsWillExtend)\n\t}\n\n\t// Indicate if we will be standalone for checking resource reservations, etc.\n\tjs.setJetStreamStandAlone(standAlone && !canExtend)\n\n\t// Enable accounts and restore state before starting clustering.","sourceCodeStart":492,"sourceCodeEnd":528,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream.go#L492-L528","documentation":"JetStream enablement: the server failed while registering its internal API/system subscriptions (e.g. $JS.API subject handlers) after the JetStream instance was configured; the wrapped error identifies the failing subscription setup call.","triggerScenarios":"s.setJetStreamExportSubs() returns an error while setting up the $JS.API internal subscriptions — typically because internal account/subscription setup failed (e.g. system account not resolvable, subscribe errors on internal clients).","commonSituations":"Missing or misconfigured system account required for JetStream API routing; internal client/subscription failures during startup; resource exhaustion preventing new subscriptions.","solutions":["Ensure a system account is configured (system_account: <name> in config) and resolvable","Check server logs just above this error for the underlying wrapped cause and fix that first","Restart the server after config correction","Verify accounts resolver setup (memory/nats resolver) is working so the system account exists"],"exampleFix":"// before\n// no system_account in nats-server config\n// after\naccounts { SYS { users: [ { user: sys, password: sys } ] } }\nsystem_account: SYS\njetstream { store_dir: \"/var/lib/nats/js\" }","handlingStrategy":"validation","validationCode":"// Ensure the system account exists before enabling JetStream:\n// config must contain: system_account: <account name declared in accounts{}>\n// and the resolver must be able to resolve it.\n// grep -q 'system_account' /etc/nats/nats-server.conf || exit 1","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always configure a system account when enabling JetStream","Read the full wrapped cause in logs before changing settings","Test JetStream enable in staging with the same account resolver setup","Keep internal subscription limits high enough for $JS.API internal subs"],"tags":["jetstream","subscriptions","internal-api","startup"],"backgroundTag":"jetstream-startup-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}