What causes "empty user name not allowed" in nats-io/nats-server?

Provide a non-empty username on the MQTT client connection options.

empty user name not allowed

Error message

empty user name not allowed

What it means

When the CONNECT packet's username flag is set, the username string must be non-empty; NATS rejects empty usernames with return code BadUserOrPassword (server/mqtt.go:3949). This is a parse/auth-stage rejection after the username has been decoded and stored in c.opts.Username.

Source

Thrown at server/mqtt.go:240

)

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
	authOverride bool
	sessmgr      mqttSessionManager

View on GitHub (pinned to 3a66a489d2)

Solutions

Provide a non-empty username on the MQTT client connection options.
If anonymous connection is intended, clear the username flag instead of sending an empty username.
Check that the env/config value feeding the username is actually populated at connect time.

Example fix

// before
opts.SetUsername(os.Getenv("MQTT_USER")) // may be empty
// after
if u := os.Getenv("MQTT_USER"); u != "" { opts.SetUsername(u) }

Defensive patterns

Strategy: validation

Validate before calling

// client side
if username == "" && usernameFlagSet {
    return fmt.Errorf("username flag set but username is empty")
}

Try / catch

// client side: on bad-username-or-password CONNACK mentioning empty username, verify credential env/config and reconnect

Prevention

Fail fast at startup if required credentials are empty (e.g. os.Exit on empty MQTT_USER).
Only call SetUsername when the value is non-empty.
Log credential presence (not values) during connection setup.

When it happens

Trigger: A CONNECT packet with mqttConnFlagUsernameFlag set but a zero-length username string (test case: ...,0,0 for the username field), so c.opts.Username equals _EMPTY_.

Common situations: Client configs with username:"" while the library still sets the username flag, environment-driven config where the username env var is unset/empty, or hand-encoded packets.

Related errors

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