Docs

Cloud Native Message Engine

MQTT introduction

Notice regarding MQTT scaling and upgrade risks

Impacts of scaling and upgrading

The cloud-native messaging engine—MQTT cloud service is built on EMQx Enterprise Edition. The cluster upgrade process involves first scaling out new nodes in the cluster, then scaling in old nodes. The entire process lasts approximately 1–5 minutes (depending on the cluster specification).

During the upgrade and scaling process, existing connections established by MQTT clients will be disconnected, after which clients will re-establish new connections. Since common MQTT-related clients are configured without automatic reconnection, please check whether the MQTT client has actively enabled AutomaticReconnect:

If the client is configured for automatic reconnection, there is no need to be concerned about the client automatically restoring the connection.

If the client is not configured for automatic reconnection but actively detects Connection Lost or other connection exceptions and then actively performs Reconnect, connections can be re-established in this scenario.

If the client is not configured for automatic reconnection and does not detect connection exceptions to perform active Reconnect, the connection will be disconnected, and the client will not automatically reconnect. In this case, it is necessary to rebuild the MQTT Client to reconnect or Restart the client service.

We generally recommend that business applications implement an automatic reconnection mechanism or actively detect exceptions to rebuild connections or clients. If business constraints prevent this configuration, pay attention to whether the business needs to be restarted during the upgrade process.

Please note that the cloud service may encounter situations such as physical machine node degraded health, emergency CVE vulnerability hot upgrades, and other scenarios that involve active maintenance operations. In production environments, the MQTT client reconnection strategy should be strictly verified to prevent business interruptions caused by active maintenance operations or occasional network fluctuations.

Last updated: 2026.01.26 16:05:27