MQTT clients over websocket must connect to the Websocket po

Error message

MQTT clients over websocket must connect to the Websocket port, not the MQTT port

What it means

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.

Source

Thrown at server/mqtt.go:225

	sparkbDDEATH = "DDEATH"
)

var (
	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")

View on GitHub (pinned to 3a66a489d2)

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

Example fix

// before
client.connect({ url: 'ws://nats.example:1883' })
// after: use the websocket port configured on the server
client.connect({ url: 'ws://nats.example:8080' })

Defensive patterns

Strategy: validation

Validate before calling

// Ensure scheme matches the port before connecting
if url.Scheme.startsWith("ws") && port == mqttTcpPort { throw new Error("use the websocket port") }

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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