WebSocket MQTT connection fails (HTTP 400 Bad Request) for MQTT 3.1 clients

[christopher-rtf]

Describe the bug

Summary
MQTT v3.1 clients are unable to connect to RabbitMQ via WebSockets: RabbitMQ is actively denying web socket clients with their Sec-WebSocket-Protocol header set to 'mqttv3.1'.

Note that this issue did not occur when tested with RabbitMQ v3.11.

Severity
This issue is blocking, preventing upgrades from RabbitMQ v3.11 to RabbitMQ v4.2.1.

Test environment
RabbitMQ v4.2.1, 3 pods in a Kubernetes cluster on Azure (using the Kubernetes Cluster Operator and NGINX as the reverse proxy ingress (mapped to port 15675); both the rabbitmq_mqtt and rabbitmq_web_mqtt plug-ins are installed.

Reproduction steps

1. Install RabbitMQ v4.2.1, the rabbitmq_mqtt plug-in and the rabbitmq_web_mqtt plug-in.
2. Connect via MQTT v3.1 and v3.1.1 clients (over http, using WebSockets).
3. The MQTT v3.1 clients are rejected via HTTP 400 (i.e. RabbitMQ rejects the 'mqttv3.1' 'client-offered protocol'); the MQTT v3.1.1 clients can connect via WebSockets without incident.

Expected behavior

RabbitMQ should accept the MQTT 3.1 clients (as MQTT v3.1 is explicitly listed as supported in the MQTT plug-in), matching its previous behavior in RabbitMQ v3.11.

Additional context

**Sample RabbitMQ log output from kubectl ***
Here's the output of kubectl logs -f -l app.kubernetes.io/component=rabbitmq, first showing a successful connection from an MQTT 3.1.1 client and then a series of failures from MQTT 3.1 clients.

2025-11-23 18:13:25.735563+00:00 [info] <0.13744.0> Accepting Web MQTT connection 10.244.2.11:40670 -> 10.244.3.40:15675
2025-11-23 18:13:25.771073+00:00 [info] <0.13744.0> Accepted Web MQTT connection 10.244.2.11:40670 -> 10.244.3.40:15675 for client ID 12345678-1234-1234-1234-1234567890ab
2025-11-23 18:13:26.075945+00:00 [error] <0.13749.0> Web MQTT: 'mqtt' not included in client offered subprotocols: [<<"mqttv3.1">>]
2025-11-23 18:13:26.076101+00:00 [info] <0.13749.0> Web MQTT closing connection undefined
2025-11-23 18:13:26.144714+00:00 [error] <0.12803.0> Web MQTT: 'mqtt' not included in client offered subprotocols: [<<"mqttv3.1">>]
2025-11-23 18:13:26.145030+00:00 [info] <0.12803.0> Web MQTT closing connection undefined
2025-11-23 18:13:26.157174+00:00 [error] <0.12154.0> Web MQTT: 'mqtt' not included in client offered subprotocols: [<<"mqttv3.1">>]
2025-11-23 18:13:26.157352+00:00 [info] <0.12154.0> Web MQTT closing connection undefined
2025-11-23 18:13:26.253438+00:00 [error] <0.12805.0> Web MQTT: 'mqtt' not included in client offered subprotocols: [<<"mqttv3.1">>]
2025-11-23 18:13:26.253593+00:00 [info] <0.12805.0> Web MQTT closing connection undefined

Screenshots of delta between requests (courtesy of Proxyman)


As seen in these screenshots, the principal difference in the two http(s) mqtt-via-websocket requests is whether MQTT 3.1.1 ('mqtt') or MQTT 3.1 ('mqttv3.1') is specified as the Sec-WebSocket-Protocol; the MQTT 3.1.1 (topmost) call succeeds.

Is there a known workaround to this issue? Or a way that I can help fix the issue?

[michaelklishin]

We need an executable way to reproduce.

[christopher-rtf]

Thank you, @michaelklishin.

Here is a minimal repro consisting of a RabbitMQ server installation (in a Docker container) and a short client MQTT connection script (written in cross-platform Swift). This entire repro may be run on macOS, on Linux or under WSL in Windows.

For the MQTT v3.1 vs v3.1.1 tests, I used the Swift working group's official (and widespread) NIO and MQTT client libraries. To keep things simple, the two sample client apps use the exactly same code (except for the referenced MQTT client library version and the client ID).

Setup procedure for minimal repro

Step 1: Install and configure RabbitMQ
1a. Install RabbitMQ as a Docker container
$ docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 -p 15675:15675 rabbitmq:4.2.1-management

1b. Install mqtt and web_mqtt plug-ins
From a second terminal, open a shell within the running RabbitMQ container:
$ docker exec -it rabbitmq /bin/bash
$ rabbitmq-plugins enable rabbitmq_mqtt
$ rabbitmq-plugins enable rabbitmq_web_mqtt

1c. Add a user
$ rabbitmqctl add_user mqttuser carrotsnomnom
$ rabbitmqctl set_permissions -p / mqttuser ".* " ".* " ".* "
$ rabbitmqctl set_user_tags mqttuser administrator

Step 2: Install Swift on the client (on the same host computer; WSL is fine)
https://www.swift.org/install/linux/
or
https://www.swift.org/install/macos/

Running the tests (Linux, macOS or WSL)

MQTT v3.1 WebSocket test
TestMqtt3_1.zip

$ cd TestMqtt3_1
$ swift run

The client will output:

MQTT conection failed: websocketUpgradeFailed

And RabbitMQ (i.e. its terminal instance or log) will output:

2025-11-24 16:09:04.225960+00:00 [error] <0.1572.0> Web MQTT: 'mqtt' not included in client offered subprotocols: [<<"mqttv3.1">>]
2025-11-24 16:09:04.226192+00:00 [info] <0.1572.0> Web MQTT closing connection undefined

MQTT v3.1.1 WebSocket test
TestMqtt3_1_1.zip

$ cd ../TestMqtt3_1_1
$ swift run

The client will output:

MQTT successfully connected

And RabbitMQ (i.e. its terminal instance or log) will output:

2025-11-24 16:10:21.450893+00:00 [info] <0.1578.0> Accepting Web MQTT connection 192.168.65.1:30326 -> 172.17.0.2:15675
2025-11-24 16:10:21.456495+00:00 [info] <0.1578.0> Accepted Web MQTT connection 192.168.65.1:30326 -> 172.17.0.2:15675 for client ID client_mqtt_3_1_1
2025-11-24 16:10:21.462436+00:00 [info] <0.1578.0> Web MQTT closing connection 192.168.65.1:30326 -> 172.17.0.2:15675

[michaelklishin]

2025-11-24 16:09:04.225960+00:00 [error] <0.1572.0> Web MQTT: 'mqtt' not included in client offered subprotocols: [<<"mqttv3.1">>]

is very specific about what's going on: the client offers mqttv3.1 for its WebSocket subprotocol name while the Web MQTT plugin expects mqtt.

RabbitMQ 3.1.1 is from 2013. MQTT 3.1.1 is from 2014.

So RabbitMQ 3.1.1 could not possibly have had support for MQTT 3.1.1.

The current value, mqtt, is used as of 1180429 and somehow it works just fine with multiple WebSockets-based clients.

[christopher-rtf]

Hi @michaelklishin

The current version we have deployed is RabbitMQ v3.11.28, released in December 2023 (not the very old v3.1.1). That version supported clients using the 'mqttv3.1' protocol tag.

Historically, 'mqttv3.1' is the unofficial WebSocket protocol tag used by a lot of MQTT v3.1 clients. The 'mqtt' WebSocket protocol tag wasn't standardized until MQTT v3.1.1.

For instance, Mosquitto's client library used the 'mqttv3.1' WebSocket subprotocol to be compatible with other implementations:
Change WebSocket subprotocol name to mqttv3.1 to make future changes easier and for compatibility with other implementations.
https://mosquitto.org/blog/index-11.html

I'm really surprised that this issue hasn't cropped up before, especially since RabbitMQ accepted the protocol tag all the way through RabbitMQ v3.11.28 (but then it broke in v3.12 and later, when the new "native MQTT" functionality was introduced).

Is is possible to update RabbitMQ to accept this widely-used client protocol tag again, to be able to support MQTT v3.1? If not, what is the recommended workaround (e.g. proxying all MQTT connections through an old version of RabbitMQ for a few years until the final in-field clients get updated)?

[lukebakken]

I don't have a Web MQTT setup handy, but this PR should address this issue:

#15008

[michaelklishin]

@lukebakken you can use the rabbitmq_web_mqtt_examples plugin for testing.

[lukebakken]

OK I'll see if I can get the client to send mqttv3.1

[lukebakken]

That was too easy. With this patch...

diff --git a/deps/rabbitmq_web_mqtt_examples/priv/echo.html b/deps/rabbitmq_web_mqtt_examples/priv/echo.html
index d9b59b3856..8686268c93 100644
--- a/deps/rabbitmq_web_mqtt_examples/priv/echo.html
+++ b/deps/rabbitmq_web_mqtt_examples/priv/echo.html
@@ -108,6 +108,7 @@
         var options = {
             timeout: 3,
             keepAliveInterval: 30,
+            mqttVersion: 3,
             onSuccess: function () {
                 debug("CONNECTION SUCCESS");
                 client.subscribe("test", {qos: 1});

I can confirm via chrome dev tools that mqttv3.1 is sent and received as expected when #15008 is in place:

---

WITHOUT #15008 and WITH setting mqttVersion: 3, the following is logged by RabbitMQ:

2025-11-24 11:55:10.692177-08:00 [error] <0.673.0> Web MQTT: 'mqtt' not included in client offered subprotocols: [<<"mqttv3.1">>]

[christopher-rtf]

One quick addition:

To be clear, the sample client code works under RabbitMQ v3.11 without incident. It's just the newer releases of RabbitMQ which break the MQTT v3.1 (over WebSocket) client.

To demonstrate this, swap in RabbitMQ v3.11.x in step 1 of the above repro.
$ docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 -p 15675:15675 rabbitmq:3.11-management
[and follow steps 1b and 1c to add the plug-ins and user info]

And to break the MQTT v3.1 sample client again, stop that container and upgrade to RabbitMQ v4.2.1.
$ docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 -p 15675:15675 rabbitmq:4.2.1-management
[and follow steps 1b and 1c to add the plug-ins and user info]

[lhoguin]

That's because the check was added with the MQTT 5 work, and mqttv3.1 is not listed in https://www.iana.org/assignments/websocket/websocket.xhtml so we didn't realise.

We do test it against v3.1.0 but perhaps the emqtt client only sends mqtt for all protocol versions.

A test for this could be done just sending an HTTP request to establish a Websocket connection with the protocol set to mqttv3.1 and checking the HTTP response.