npm / mqtt
mqtt
What changed in mqtt 5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
8 breaking4 security3 new APIs and options6 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initmqtt 521 changes
Breaking changes 8
An acknowledgment that does not match the pending command for its message id is dropped and reported through error.
A getter provides access to negotiated keepalive now that CONNACK no longer mutates the options object.
A getter provides access to negotiated server properties now that CONNACK no longer mutates the options object.
The cap measures total wire size rather than Remaining Length, so it triggers on packets a few bytes smaller than before.
CONNACK properties no longer mutate the caller's options object; read negotiated values from the client getters instead.
Invalid or non-integer values outside 1..65535 are ignored; 65535 is enforced and advertised instead.
Protocol violations drop the connection, with reconnect remaining armed.
A refused CONNACK always closes the socket, including when reconnectOnConnackError is false.
Security 4
Unsolicited or out-of-spec AUTH packets are rejected rather than crashing the process.
The advertised Receive Maximum is enforced for inbound QoS 2 messages, preventing an unbounded incoming store.
SUBACK reason-code counts are checked against subscriptions sent, preventing crashes or incorrect subscription reports.
Unsolicited MQTT 5 Topic Aliases are rejected rather than crashing the process; the unregistered-alias case reports reason code 0x82.
New APIs and options 3
PacketPump is newly exported from src/lib/shared.ts.
PendingCommand is newly exported from the entry point.
Topic validation functions are exported for external use.
Fixes and other changes 6
Reconnects instead of ending a client whose stream is already destroyed.
Schedules browser process.nextTick with queueMicrotask.
AUTH reason code 0 now ends the exchange successfully instead of producing an error with an empty reason string.
Duplicate CONNACK packets are rejected instead of rerunning connection setup mid-session.
An explicit servername (SNI) is no longer overwritten when connecting over TLS.
WebSocket connections now support relative URLs.