nats-io/nats-server · error

mqtt requires server name to be explicitly set

Error message

mqtt requires server name to be explicitly set

What it means

In cluster or gateway mode, MQTT persistent sessions must be routed to the correct server, which requires an explicitly configured server name. If MQTT is enabled, `server_name` is empty, and either `cluster.port` or `gateway.port` is set, config validation (server/mqtt.go:706) returns this error and the server refuses to start.

Source

Thrown at server/mqtt.go:229

	sparkbNamespaceTopicPrefix    = []byte("spBv1.0/")
	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")

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set `server_name: "uniquename"` in the server config (or pass `--server_name`)
2. If clustering/gateways are not intended, remove the `cluster`/`gateway` port configuration so the check is skipped
3. Ensure every node in the cluster has a distinct explicit server_name

Example fix

# before
mqtt { listen: 1883 }
cluster { port: 6222 }
# after
server_name: "nats-1"
mqtt { listen: 1883 }
cluster { port: 6222 }

// Pre-startup config check
if cfg.MQTT != nil && cfg.ServerName == "" && (cfg.Cluster.Port != 0 || cfg.Gateway.Port != 0) {
  return errors.New("server_name required when MQTT runs in cluster/gateway mode")
}

When it happens

Trigger: Enabling `mqtt { }` in a config that also defines a cluster or gateway but omits `server_name`; running `nats-server` with `-cluster` flags plus MQTT without `--server_name`.

Common situations: Adding MQTT to an existing clustered deployment and forgetting the name; configs generated by templates that skip server_name for single-node setups; TestMQTTServerNameRequired covers exactly this validation.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• duplicate server name
• remote leafnode has same cluster name
• system limit reached
• mqtt authentication username not compatible with presence of
• jetstream cluster requires `server_name` to be set

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