when client ID is empty, clean session flag must be set to 1

Error message

when client ID is empty, clean session flag must be set to 1

What it means

An MQTT client that connects with an empty client ID must request a clean session (clean session flag = 1), per spec [MQTT-3.1.3-6]; otherwise a persistent session could not be keyed. When the parsed client ID is empty and the clean-session bit is not set, the server returns this error with return code IdentifierRejected (server/mqtt.go:3881).

Source

Thrown at server/mqtt.go:238

	mqttFlapCleanItvl    = mqttSessFlappingCleanupInterval
	mqttRetainedCacheTTL = mqttDefaultRetainedCacheTTL
)

var (
	errMQTTNotWebsocketPort           = errors.New("MQTT clients over websocket must connect to the Websocket port, not the MQTT port")
	errMQTTTopicFilterCannotBeEmpty   = errors.New("topic filter cannot be empty")
	errMQTTMalformedVarInt            = errors.New("malformed variable int")
	errMQTTSecondConnectPacket        = errors.New("received a second CONNECT packet")
	errMQTTServerNameMustBeSet        = errors.New("mqtt requires server name to be explicitly set")
	errMQTTUserMixWithUsersNKeys      = errors.New("mqtt authentication username not compatible with presence of users/nkeys")
	errMQTTTokenMixWIthUsersNKeys     = errors.New("mqtt authentication token not compatible with presence of users/nkeys")
	errMQTTAckWaitMustBePositive      = errors.New("ack wait must be a positive value")
	errMQTTJSAPITimeoutMustBePositive = errors.New("JS API timeout must be a positive value")
	errMQTTStandaloneNeedsJetStream   = errors.New("mqtt requires JetStream to be enabled if running in standalone mode")
	errMQTTConnFlagReserved           = errors.New("connect flags reserved bit not set to 0")
	errMQTTWillAndRetainFlag          = errors.New("if Will flag is set to 0, Will Retain flag must be 0 too")
	errMQTTPasswordFlagAndNoUser      = errors.New("password flag set but username flag is not")
	errMQTTCIDEmptyNeedsCleanFlag     = errors.New("when client ID is empty, clean session flag must be set to 1")
	errMQTTEmptyWillTopic             = errors.New("empty Will topic not allowed")
	errMQTTEmptyUsername              = errors.New("empty user name not allowed")
	errMQTTTopicIsEmpty               = errors.New("topic cannot be empty")
	errMQTTPacketIdentifierIsZero     = errors.New("packet identifier cannot be 0")
	errMQTTUnsupportedCharacters      = errors.New("character not supported for MQTT topics")
	errMQTTInvalidSession             = errors.New("invalid MQTT session")
	errMQTTInvalidRetainFlags         = errors.New("invalid retained message flags")
	errMQTTInvalidRetainedMessage     = errors.New("invalid retained message")
	errMQTTSessionCollision           = errors.New("stored session does not match client ID")
	errMQTTInvalidPublishLength       = errors.New("invalid publish message, variable header exceeds remaining length")
	errMQTTAckPipelineStopped         = errors.New("QoS1 PUBACK pipeline has shut down while admitting a message, " +
		"abandoning the wait for its JetStream ack; failing the connection, " +
		"the client will re-send unacknowledged PUBLISH packets on reconnect")
)

type srvMQTT struct {
	listener     net.Listener
	listenerErr  error

View on GitHub (pinned to 3a66a489d2)

Solutions

Set CleanSession=true on the client when using an empty client ID.
Provide a non-empty, stable client ID if a persistent session is required.
Have the client generate a unique ID per process instance before connecting.

Example fix

// before
opts := mqtt.NewClientOptions().SetClientID("").SetCleanSession(false)
// after
opts := mqtt.NewClientOptions().SetClientID("client-1").SetCleanSession(false)
// or: SetClientID("").SetCleanSession(true)

Defensive patterns

Strategy: validation

Validate before calling

// client side, before Connect()
if clientID == "" && !cleanSession {
    return fmt.Errorf("empty client ID requires clean session = true")
}

Try / catch

// client side: on CONNACK identifier-rejected with this message, set CleanSession=true or generate a client ID and reconnect

Prevention

Generate a unique, stable client ID at process start instead of leaving it empty.
Default CleanSession=true unless you deliberately manage persistent sessions.
Log the effective client ID and clean-session setting on every connect.

When it happens

Trigger: A CONNECT packet with a zero-length client ID and the mqttConnFlagCleanSession bit clear (test case: flags byte 0, client ID length 0), received on an existing client whose cid is empty.

Common situations: Clients that generate a random ID only sometimes (e.g. empty string on reconnect) while also requesting persistent sessions; embedded clients defaulting ClientID to "" and CleanSession to false.

Related errors

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