nats-io/nats-server · error

%v for account %q, session %q

Error message

%v for account %q, session %q

What it means

Not a distinct failure itself: formatError is the closure in the MQTT session-setup code that decorates an underlying error with the account and session (client ID) context, producing '<err> for account "X", session "Y"'. Seeing it means some other session-establishment error occurred and was annotated.

Source

Thrown at server/mqtt.go:4101

	// Register this client ID the "locked" map for the duration if this function.
	asm.sessLocked[cid] = struct{}{}
	// And remove it on exit, regardless of error or not.
	defer func() {
		asm.mu.Lock()
		delete(asm.sessLocked, cid)
		asm.mu.Unlock()
	}()

	// Is the client requesting a clean session or not.
	cleanSess := cp.flags&mqttConnFlagCleanSession != 0
	// Session present? Assume false, will be set to true only when applicable.
	sessp := false
	// Do we have an existing session for this client ID
	es, exists := asm.sessions[cid]
	asm.mu.Unlock()
	formatError := func(err error) error {
		return fmt.Errorf("%v for account %q, session %q", err, c.acc.GetName(), cid)
	}

	// The session is not in the map, but may be on disk, so try to recover
	// or create the stream if not.
	if !exists {
		es, exists, err = asm.createOrRestoreSession(cid, s.getOpts())
		if err != nil {
			if err == errMQTTSessionCollision {
				sendConnAck(mqttConnAckRCIdentifierRejected, false)
			}
			return formatError(err)
		}
	}
	if exists {
		// Clear the session if client wants a clean session.
		// Also, Spec [MQTT-3.2.2-1]: don't report session present
		if cleanSess || es.clean {
			// Spec [MQTT-3.1.2-6]: If CleanSession is set to 1, the Client and

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Look at the wrapped/underlying error text before 'for account' to find the real cause
2. Fix the session error (storage, limits, state) identified by the inner error

When it happens

Trigger: Thrown at server/mqtt.go:4101 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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