nats-io/nats-server · error

jetstream account not registered

Error message

jetstream account not registered

What it means

enableAllJetStreamServiceImportsAndMappings adds the JetStream API service import from the system account into this account so the account can reach $JS.API subjects. If the account's srv pointer is nil, the account is not (or no longer) registered with a running server, so there is no server context under which to create the import and this error is returned. It is an internal invariant check rather than a user-facing validation.

Source

Thrown at server/jetstream.go:799

		}
		gacc.mu.Unlock()
		if err := s.configJetStream(gacc, tq); err != nil {
			return err
		}
	} else if err := s.configAllJetStreamAccounts(tq); err != nil {
		return fmt.Errorf("Error enabling jetstream on configured accounts: %v", err)
	}
	return nil
}

// enableAllJetStreamServiceImportsAndMappings turns on all service imports and mappings for jetstream for this account.
func (a *Account) enableAllJetStreamServiceImportsAndMappings() error {
	a.mu.RLock()
	s := a.srv
	a.mu.RUnlock()

	if s == nil {
		return fmt.Errorf("jetstream account not registered")
	}

	var dstAccName string
	if sacc := s.SystemAccount(); sacc != nil {
		dstAccName = sacc.Name
	}

	if !a.serviceImportExists(dstAccName, jsAllAPI) {
		// Capture si so we can turn on implicit sharing with JetStream layer.
		// Make sure to set "to" otherwise will incur performance slow down.
		si, err := a.addServiceImport(s.SystemAccount(), jsAllAPI, jsAllAPI, nil)
		if err != nil {
			return fmt.Errorf("Error setting up jetstream service imports for account: %v", err)
		}
		a.mu.Lock()
		si.share = true
		a.mu.Unlock()
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Register the account with a running server before enabling JetStream (pass it via Accounts in Options or call s.AddAccount).
2. Ensure the server is started and running before calling EnableJetStream on the account.
3. Guard against calling JetStream APIs during server shutdown/account removal in your code.
4. Check that you are not holding a stale *Account reference from before a server restart.

Example fix

// before
acc, _ := server.NewAccount("JS")
acc.EnableJetStream(nil, nil) // srv is nil -> error
// after
opts := server.DefaultOptions()
opts.Accounts = []*server.Account{acc}
s, _ := server.NewServer(opts)
go s.Start()
acc.EnableJetStream(nil, nil) // registered, works

if acc == nil || !s.Running() {
    return fmt.Errorf("account must be registered with a running server before JetStream setup")
}
if _, err := s.LookupAccount(acc.Name); err != nil {
    return fmt.Errorf("account %s not registered: %w", acc.Name, err)
}

if err := acc.EnableJetStream(limits, tq); err != nil {
    if strings.Contains(err.Error(), "not registered") {
        // re-add account to server and retry once
    }
    return err
}

When it happens

Trigger: Calling Account.EnableJetStream (or internally enableAllJetStreamServiceImportsAndMappings) on an account whose a.srv is nil - i.e. the account was created but never added to a running server, or was removed (account teardown) while JetStream setup still runs.

Common situations: Using an Account object after server shutdown or account removal; constructing an Account standalone in tests without AccountsAdd; a race where the account is being deleted concurrently with JetStream enablement.

Related errors

• error creating store for stream
• error creating store for consumer
• JS_STREAM_OFFLINE
• JS_ERR_GENERIC
• Error setting up jetstream service imports for account: %v

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