{"record":{"id":"7a92d270d6ba6d24","repo":"nats-io/nats-server","slug":"mqtt-clients-over-websocket-must-connect-to-the-we","errorCode":null,"errorMessage":"MQTT clients over websocket must connect to the Websocket port, not the MQTT port","messagePattern":"MQTT clients over websocket must connect to the Websocket port, not the MQTT port","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":225,"sourceCode":"\tsparkbDDEATH = \"DDEATH\"\n)\n\nvar (\n\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\")","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L207-L243","documentation":"This error is returned when an MQTT client that should be speaking MQTT-over-WebSocket opens a TCP connection to the MQTT port but starts its stream with an HTTP `GET` (the WebSocket upgrade handshake). The server detects the `GET ` prefix on a non-WebSocket connection (server/mqtt.go:810) and tells the client it connected to the wrong port.","triggerScenarios":"Configuring an MQTT client with `ws://` or `wss://` URL scheme but pointing it at the `mqtt_listen` port instead of the `websocket { listen }` port; running MQTT.js or another WS-capable client with the host:port of the plain MQTT listener.","commonSituations":"Copy-pasting the MQTT port into a WebSocket client URL; reverse proxies forwarding WS traffic to the MQTT port; clients auto-detecting ports and choosing ws transport when only tcp MQTT is configured.","solutions":["Point the client's ws:// or wss:// URL at the configured websocket port (the `websocket { listen: port }` value), not the mqtt_listen port","Use the plain tcp scheme (mqtt:// or mqtts:// semantics of the client) when connecting to the MQTT port","Check the server config: `mqtt { listen: <port> }` is for raw MQTT; `websocket { listen: <port> }` is for MQTT-over-WS","Fix any proxy/load-balancer routing that sends WebSocket handshakes to the MQTT port"],"exampleFix":"// before\nclient.connect({ url: 'ws://nats.example:1883' })\n// after: use the websocket port configured on the server\nclient.connect({ url: 'ws://nats.example:8080' })","handlingStrategy":"validation","validationCode":"// Ensure scheme matches the port before connecting\nif url.Scheme.startsWith(\"ws\") && port == mqttTcpPort { throw new Error(\"use the websocket port\") }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep mqtt_listen and websocket ports distinct and documented","Test client connectivity after config changes","Configure proxies to route WS upgrades only to the websocket port"],"tags":["mqtt","websocket","network","wrong-port"],"backgroundTag":"wrong-port-connection","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}