nats-io/nats-server · error

setting up internal jetstream subscriptions failed: %v

Error message

setting up internal jetstream subscriptions failed: %v

What it means

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.

Source

Thrown at server/jetstream.go:510

	s.Noticef("  Max Storage:     %s", friendlyBytes(cfg.MaxStore))
	s.Noticef("  Store Directory: \"%s\"", cfg.StoreDir)
	if cfg.Domain != _EMPTY_ {
		s.Noticef("  Domain:          %s", cfg.Domain)
	}

	if ek := opts.JetStreamKey; ek != _EMPTY_ {
		s.Noticef("  Encryption:      %s", opts.JetStreamCipher)
	}
	if opts.JetStreamTpm.KeysFile != _EMPTY_ {
		s.Noticef("  TPM File:        %q, Pcr: %d", opts.JetStreamTpm.KeysFile,
			opts.JetStreamTpm.Pcr)
	}
	s.Noticef("  API Level:       %d", JSApiLevel)
	s.Noticef("-------------------------------------------")

	// Setup our internal subscriptions.
	if err := s.setJetStreamExportSubs(); err != nil {
		return fmt.Errorf("setting up internal jetstream subscriptions failed: %v", err)
	}

	// Setup our internal system exports.
	s.Debugf("  Exports:")
	s.Debugf("     %s", jsAllAPI)
	s.setupJetStreamExports()

	standAlone, canExtend := s.standAloneMode(), s.canExtendOtherDomain()
	if standAlone && canExtend && s.getOpts().JetStreamExtHint != jsWillExtend {
		canExtend = false
		s.Noticef("Standalone server started in clustered mode do not support extending domains")
		s.Noticef(`Manually disable standalone mode by setting the JetStream Option "extension_hint: %s"`, jsWillExtend)
	}

	// Indicate if we will be standalone for checking resource reservations, etc.
	js.setJetStreamStandAlone(standAlone && !canExtend)

	// Enable accounts and restore state before starting clustering.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Ensure a system account is configured (system_account: <name> in config) and resolvable
2. Check server logs just above this error for the underlying wrapped cause and fix that first
3. Restart the server after config correction
4. Verify accounts resolver setup (memory/nats resolver) is working so the system account exists

Example fix

// before
// no system_account in nats-server config
// after
accounts { SYS { users: [ { user: sys, password: sys } ] } }
system_account: SYS
jetstream { store_dir: "/var/lib/nats/js" }

// Ensure the system account exists before enabling JetStream:
// config must contain: system_account: <account name declared in accounts{}>
// and the resolver must be able to resolve it.
// grep -q 'system_account' /etc/nats/nats-server.conf || exit 1

When it happens

Trigger: 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).

Common situations: Missing or misconfigured system account required for JetStream API routing; internal client/subscription failures during startup; resource exhaustion preventing new subscriptions.

Related errors

• monitor goroutine not running
• mqtt requires JetStream to be enabled if running in standalo
• Error enabling jetstream on configured accounts: %v
• got corrupted escaped character
• unsupported BER encoding

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