mqtt authentication username not compatible with presence of

Error message

mqtt authentication username not compatible with presence of users/nkeys

What it means

When MQTT authentication is configured via `mqtt { username/token }`, those credentials are mutually exclusive with the server's global `users`/`nkeys` authorization lists. If any users or nkeys are configured and the MQTT section also defines a username (or token), validation returns this error (server/mqtt.go:718) because the two auth mechanisms cannot be combined.

Source

Thrown at server/mqtt.go:230

	sparkbCertificatesTopicPrefix = []byte("$sparkplug/certificates/")
)

var (
	mqttPingResponse     = []byte{mqttPacketPingResp, 0x0}
	mqttProtoName        = []byte("MQTT")
	mqttOldProtoName     = []byte("MQIsdp")
	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")

View on GitHub (pinned to 3a66a489d2)

Solutions

Remove the mqtt username/token and instead give MQTT clients an entry in the `users` list (with or without password)
Or remove the global `users`/`nkeys` definitions if you intend to use only MQTT-level auth
For granular MQTT permissions, configure a dedicated user in `users` used by MQTT clients rather than the mqtt block

Example fix

# before
mqtt { username: "mqtt", password: "pwd" }
users = [{user: "app", password: "s3cret"}]
# after
users = [{user: "app", password: "s3cret"}, {user: "mqtt", password: "pwd"}]

Defensive patterns

Strategy: validation

Validate before calling

// Reject the combination before deploy
if cfg.MQTT != nil && (cfg.MQTT.Username != "" || cfg.MQTT.Token != "") && (len(cfg.Users) > 0 || len(cfg.Nkeys) > 0) {
  return errors.New("mqtt username/token cannot be combined with users/nkeys")
}

Prevention

Choose one auth model per server: users/nkeys lists OR mqtt-level credentials
Represent MQTT clients as entries in the users list for uniform auth
Run nats-server -t in CI to catch config conflicts early

When it happens

Trigger: Config `mqtt { username: "..." }` together with a `users` or `nkeys` array; adding MQTT credentials to a deployment that already uses users/nkeys for other clients.

Common situations: Adding MQTT support to an existing server secured with users/nkeys; mixing MQTT token auth with per-user credentials in one config; TestMQTTUserMixWithUsersNKeys documents this exact scenario.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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