nats-io/nats-server · error

Error setting up jetstream service imports for account: %v

Error message

Error setting up jetstream service imports for account: %v

What it means

When an account is enabled for JetStream, the server creates a service import from the system account mapping $JS.API (jsAllAPI) into the account. This error wraps any failure from addServiceImport while setting up that import, so the underlying cause (duplicate import, invalid subject, cross-account restriction) is reported as a JetStream setup failure.

Source

Thrown at server/jetstream.go:812

	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()
	}

	// Check if we have a Domain specified.
	// If so add in a subject mapping that will allow local connected clients to reach us here as well.
	if opts := s.getOpts(); opts.JetStreamDomain != _EMPTY_ {
		mappings := generateJSMappingTable(opts.JetStreamDomain)
		a.mu.RLock()
		for _, m := range a.mappings {
			delete(mappings, m.src)
		}
		a.mu.RUnlock()
		for src, dest := range mappings {
			if err := a.AddMapping(src, dest); err != nil {
				s.Errorf("Error adding JetStream domain mapping: %v", err)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped %v cause in the message to find the underlying addServiceImport failure.
2. Remove or rename conflicting service imports for the $JS.API subject in the account's configuration.
3. Let the server manage the JetStream import automatically instead of declaring it manually in config.
4. Verify a valid system account is configured (SystemAccount option) and reachable.
5. Retry after resolving; the setup is idempotent when the import already exists.

Example fix

// before (config)
accounts {
  JS { imports: [{ stream: { account: SYS, to: "$JS.API.>" , prefix: "JS" } }] }
}
// after
accounts {
  JS { jetstream: enable }
}
// server creates the $JS.API import itself

// Ensure the account does not already declare its own $JS.API service import
if acc.serviceImportExists("$SYS", "$JS.API.>") {
    return fmt.Errorf("remove manual $JS.API import; server creates it automatically")
}

if err := acc.EnableJetStream(limits, tq); err != nil {
    var cfgErr error
    if strings.Contains(err.Error(), "service imports") {
        // inspect wrapped cause, fix conflicting import in account config
    }
    return err
}

When it happens

Trigger: Account.EnableJetStream path where a.serviceImportExists(dstAccName, jsAllAPI) is false and a.addServiceImport(s.SystemAccount(), jsAllAPI, jsAllAPI, nil) fails - e.g. an import for that subject already exists pointing elsewhere, or the import conflicts with an export/mapping in the account.

Common situations: The account already has a manually configured service import for $JS.API (from JS() in config) that conflicts; account config was applied twice; operator-mode JWT constraints restrict imports; the system account is missing/misconfigured.

Related errors

• error creating store for stream
• error creating store for consumer
• JS_STREAM_OFFLINE
• JS_ERR_GENERIC
• service import not found

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