nats-io/nats-server · error

create sessions stream for account %q: %v

Error message

create sessions stream for account %q: %v

What it means

When the account's muxed MQTT sessions stream does not exist (or needs upgrading for mqtt.SessionReplicas > 1), the server attempts to create it with MaxMsgsPer=1 and the configured replicas. If creation fails with any error other than JSStreamNameExistErr (a benign race where another server created it first), this wrapped error is returned and the MQTT CONNECT fails.

Source

Thrown at server/mqtt.go:1428

		return si, nil
	}

	if si, err := lookupStream(mqttSessStreamName, "sessions"); err != nil {
		return nil, err
	} else if si == nil {
		// Create the stream for the sessions.
		cfg := &StreamConfig{
			Name:       mqttSessStreamName,
			Subjects:   []string{mqttSessStreamSubjectPrefix + as.domainTk + ">"},
			Storage:    FileStorage,
			Retention:  LimitsPolicy,
			Replicas:   replicas,
			MaxMsgsPer: 1,
		}
		if _, created, err := jsa.createStream(cfg); err == nil && created {
			as.transferUniqueSessStreamsToMuxed(s)
		} else if isErrorOtherThan(err, JSStreamNameExistErr) {
			return nil, fmt.Errorf("create sessions stream for account %q: %v", accName, err)
		}
	}

	if si, err := lookupStream(mqttStreamName, "messages"); err != nil {
		return nil, err
	} else if si == nil {
		// Create the stream for the messages.
		cfg := &StreamConfig{
			Name:      mqttStreamName,
			Subjects:  []string{mqttStreamSubjectPrefix + ">"},
			Storage:   FileStorage,
			Retention: InterestPolicy,
			Replicas:  replicas,
		}
		if _, _, err := jsa.createStream(cfg); isErrorOtherThan(err, JSStreamNameExistErr) {
			return nil, fmt.Errorf("create messages stream for account %q: %v", accName, err)
		}
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Read the inner error for the exact JetStream cause (limits, permissions, etc.).
2. Raise the account's JetStream stream/storage limits if exhausted.
3. Check cluster health; replica creation fails if enough peers aren't available.
4. Ensure JetStream is enabled for the account and the server.

// Ensure account JS tier can host the sessions stream before CONNECT
if (account.limits.jetstream.max_streams <= 0 || account.limits.jetstream.max_store <= 0) {
  throw new Error('account JetStream limits too low for MQTT');
}

try {
  await mqttConnect();
} catch (e) {
  if (/create sessions stream/.test(e.message)) {
    raiseAccountJetStreamLimits();
    return mqttConnect(); // retry after limits fixed
  }
  throw e;
}

When it happens

Trigger: jsa.createStream(cfg) for the '<account>-mqtt-sessions' stream returns an error that is not JSStreamNameExistErr — e.g. insufficient JS resources, invalid config for the account tier, or a JS API error. Triggered in mqttJSStreamConfig when setting up the sessions stream.

Common situations: Account JS tier limits (max streams, storage) exceeded; upgrading to MQTT.StreamReplicas>1 on an account whose existing stream can't be replaced; JS disabled; permissions errors.

Related errors

• create messages stream for account %q: %v
• create QoS2 incoming messages stream for account %q: %v
• create QoS2 outgoing PUBREL stream for account %q: %v
• create retained messages stream for account %q: %v
• error creating store for stream

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