nats-io/nats-server · error

password flag set but username flag is not

Error message

password flag set but username flag is not

What it means

MQTT forbids sending a password without a username: per spec [MQTT-3.1.2-22], the password flag requires the username flag. During CONNECT parsing (server/mqtt.go:3856), if hasPassword is true but hasUser is false, the connection is rejected with this error.

Solutions

  1. Configure the MQTT client with both username and password, or drop the password.
  2. Fix hand-encoded packets so the username flag (bit 7) accompanies the password flag (bit 1).
  3. Check the client's broker URI/config: many clients silently omit the username when it is empty.

Example fix

// before
flags := mqttConnFlagPasswordFlag // password without username
// after
flags := mqttConnFlagUsernameFlag | mqttConnFlagPasswordFlag
Defensive patterns

Strategy: validation

Validate before calling

// client side
if hasPassword && !hasUsername {
    return fmt.Errorf("password requires a username per MQTT spec")
}

Try / catch

// client side: on 'password flag set but username flag is not', supply both credentials or drop the password

Prevention

When it happens

Trigger: A CONNECT packet sets bit 1 (password flag) but not bit 7 (username flag), e.g. flags byte mqttConnFlagPasswordFlag alone as in the test case.

Common situations: Clients configured with only a password (no username) in the connection options, or hand-built packets setting the password bit independently of the username bit.

Related errors

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

Appendix: source

Thrown at server/mqtt.go:237

	mqttSessJailDur      = mqttSessFlappingJailDur
	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

View on GitHub (pinned to 3a66a489d2)