{"record":{"id":"3e34a0de80b30ba3","repo":"nats-io/nats-server","slug":"mqtt-requires-server-name-to-be-explicitly-set","errorCode":null,"errorMessage":"mqtt requires server name to be explicitly set","messagePattern":"mqtt requires server name to be explicitly set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":229,"sourceCode":"\tsparkbNamespaceTopicPrefix    = []byte(\"spBv1.0/\")\n\tsparkbCertificatesTopicPrefix = []byte(\"$sparkplug/certificates/\")\n)\n\nvar (\n\tmqttPingResponse     = []byte{mqttPacketPingResp, 0x0}\n\tmqttProtoName        = []byte(\"MQTT\")\n\tmqttOldProtoName     = []byte(\"MQIsdp\")\n\tmqttSessJailDur      = mqttSessFlappingJailDur\n\tmqttFlapCleanItvl    = mqttSessFlappingCleanupInterval\n\tmqttRetainedCacheTTL = mqttDefaultRetainedCacheTTL\n)\n\nvar (\n\terrMQTTNotWebsocketPort           = errors.New(\"MQTT clients over websocket must connect to the Websocket port, not the MQTT port\")\n\terrMQTTTopicFilterCannotBeEmpty   = errors.New(\"topic filter cannot be empty\")\n\terrMQTTMalformedVarInt            = errors.New(\"malformed variable int\")\n\terrMQTTSecondConnectPacket        = errors.New(\"received a second CONNECT packet\")\n\terrMQTTServerNameMustBeSet        = errors.New(\"mqtt requires server name to be explicitly set\")\n\terrMQTTUserMixWithUsersNKeys      = errors.New(\"mqtt authentication username not compatible with presence of users/nkeys\")\n\terrMQTTTokenMixWIthUsersNKeys     = errors.New(\"mqtt authentication token not compatible with presence of users/nkeys\")\n\terrMQTTAckWaitMustBePositive      = errors.New(\"ack wait must be a positive value\")\n\terrMQTTJSAPITimeoutMustBePositive = errors.New(\"JS API timeout must be a positive value\")\n\terrMQTTStandaloneNeedsJetStream   = errors.New(\"mqtt requires JetStream to be enabled if running in standalone mode\")\n\terrMQTTConnFlagReserved           = errors.New(\"connect flags reserved bit not set to 0\")\n\terrMQTTWillAndRetainFlag          = errors.New(\"if Will flag is set to 0, Will Retain flag must be 0 too\")\n\terrMQTTPasswordFlagAndNoUser      = errors.New(\"password flag set but username flag is not\")\n\terrMQTTCIDEmptyNeedsCleanFlag     = errors.New(\"when client ID is empty, clean session flag must be set to 1\")\n\terrMQTTEmptyWillTopic             = errors.New(\"empty Will topic not allowed\")\n\terrMQTTEmptyUsername              = errors.New(\"empty user name not allowed\")\n\terrMQTTTopicIsEmpty               = errors.New(\"topic cannot be empty\")\n\terrMQTTPacketIdentifierIsZero     = errors.New(\"packet identifier cannot be 0\")\n\terrMQTTUnsupportedCharacters      = errors.New(\"character not supported for MQTT topics\")\n\terrMQTTInvalidSession             = errors.New(\"invalid MQTT session\")\n\terrMQTTInvalidRetainFlags         = errors.New(\"invalid retained message flags\")\n\terrMQTTInvalidRetainedMessage     = errors.New(\"invalid retained message\")\n\terrMQTTSessionCollision           = errors.New(\"stored session does not match client ID\")","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L211-L247","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Set `server_name: \"uniquename\"` in the server config (or pass `--server_name`)","If clustering/gateways are not intended, remove the `cluster`/`gateway` port configuration so the check is skipped","Ensure every node in the cluster has a distinct explicit server_name"],"exampleFix":"# before\nmqtt { listen: 1883 }\ncluster { port: 6222 }\n# after\nserver_name: \"nats-1\"\nmqtt { listen: 1883 }\ncluster { port: 6222 }","handlingStrategy":"validation","validationCode":"// Pre-startup config check\nif cfg.MQTT != nil && cfg.ServerName == \"\" && (cfg.Cluster.Port != 0 || cfg.Gateway.Port != 0) {\n  return errors.New(\"server_name required when MQTT runs in cluster/gateway mode\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set a unique server_name in clustered deployments","Validate configs with nats-server -t before restart","Template clustered configs with mandatory server_name fields"],"tags":["mqtt","configuration","server-name","cluster"],"backgroundTag":"missing-required-config","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}