Book a consultation

HiveMQ Platform: The Broker, the 2026 Suite and the Editions

HiveMQ Cluster: Replicas, Failure Detection and Overload Protection

How a HiveMQ cluster works: masterless nodes, replica count 2, heartbeat failure detection, overload protection, node loss and what the docs say on WAN.

Vladimir Romanov


A HiveMQ cluster is a group of broker nodes that behave as one logical broker, with no primary node and with persistent data replicated between members. This page explains what HiveMQ’s documentation says about replicas, failure detection, overload protection, node loss and network partitions, and then lists the questions we would ask before sizing one. It sits under the HiveMQ Platform page.

How a HiveMQ cluster is built

HiveMQ describes a masterless cluster: every node can accept client connections, and nodes can be added or removed at runtime. We have not found HiveMQ using the term shared-nothing, so we describe it as masterless with replicated persistent data.

  • What is replicated. HiveMQ lists retained messages, the subscriptions and queued messages of persistent sessions, in-flight message state, and Data Hub schemas and policies.
  • Replica count. The default is 2, meaning one original and one copy. It cannot exceed the node count, and below 2 data can be lost when a node restarts. When cluster size changes, data is redistributed.
  • Discovery. Static, multicast, broadcast, or an extension. HiveMQ’s cluster guide says discovery extensions for common use cases such as dynamic discovery on AWS or Docker are available from HiveMQ. It also says the minimal cluster configuration “is only recommended for testing purposes in local networks”.
  • Transport. TCP is recommended, TLS transport is available, and the guide says “UDP transport is not suitable for production environments”.
Dense bundles of green-lit network cables running into a server rack
Redundant cabling behind a rack: a cluster is only as independent as the network and power its nodes share.

Replica count 2 in practice

The figure shows a three-node cluster with replica count 2. Each piece of persistent data has an original on one node and a copy on another. When node 3 fails, its data survives on the nodes holding the copies, and the cluster redistributes.

Three-node cluster with replica count 2 and one failed node Nodes 1 and 2 are healthy and each hold originals and copies of data sets A, B and C. Node 3 has failed and is drawn dashed. Data set C has its original on node 3 and its copy on node 1, so it survives. Clients reconnect to nodes 1 and 2. Node 1 A original C copy healthy Node 2 B original A copy healthy Node 3 (failed) C original (lost) B copy (lost) missed heartbeat Data set C survives on node 1, data set B on node 2 A second permanent failure before redistribution completes could make data unavailable.
With replica count 2, one node can fail and every data set still has a copy; losing more nodes than the replica count permanently is the case HiveMQ warns about.

The layout is schematic: HiveMQ does not publish the placement algorithm in the pages we read.

Failure detection, node loss and network partition

Detection. HiveMQ states that a heartbeat and a TCP health check detect failure, and a node that misses the heartbeat timeout is removed by the node that sent to it.

Node loss, as documented. Clients connected to the failed node reconnect to another node. Data is redistributed across the remaining nodes. If permanently failed nodes exceed the replica count, persistent data can become unavailable; HiveMQ’s recovery path is the Recovery Tool for data folders and a live backup import (available since 4.9.0). HiveMQ’s documentation warns when all nodes, or more than the replica count, fail.

Network partition, as documented. HiveMQ describes a node made unreachable by a network split rejoining through a cluster merge process. The page we read does not say how conflicting state is resolved, and does not use the term split brain. We treat that as an open question to put to HiveMQ.

EventWhat HiveMQ documentsWhat we would test
One node fails (replica count 2)Heartbeat detects it, the node is removed, data is redistributed from copiesClient reconnect time and message loss on QoS 1
More nodes fail than the replica countPersistent data can become unavailable; Recovery Tool and backup importThe recovery procedure, timed
Node unreachable, then returnsCluster merge processWhich state wins, on your version
OverloadCredits, backpressure, ignored packetsClient behaviour when throttled

Shutdown order. For a full shutdown, HiveMQ describes taking nodes down one at a time, with the last node down starting first. For rolling upgrades it notes a temporary extra node helps when CPU is above 60 percent.

A fix in 4.57 (3 November 2026) addressed clusters that stopped accepting nodes after a failed join. We read that as a reminder that cluster join and rejoin paths are where bugs have lived, so test them on your version.

Overload protection and backpressure

HiveMQ’s overload protection is on by default. Each node computes a level every 100 milliseconds, and all nodes apply the highest level reported. HiveMQ says the restriction applies to individual clients that significantly increase cluster load, not to the cluster as a whole. Each client has 100 credits; publish, subscribe and unsubscribe packets cost credits. At zero, the broker stops reading from that client’s TCP socket, which pushes backpressure onto the TCP stack, and ignores incoming packets including PINGREQ.

In our view, this is the right design for a broker, and the consequence is operational. A client that goes quiet may be throttled, not broken. A keep-alive timeout during a burst can look like a network fault. Log overload events and alert on them. Also confirm that client libraries reconnect with a back-off and a random delay, so that a recovered node is not hit by every client in the same second.

Questions to ask before sizing a HiveMQ cluster

  1. How many node losses must the plant survive? This sets the replica count.
  2. What is the reconnect storm? Count clients that reconnect at once after a switch reboot, and the subscriptions each resends.
  3. How much retained and queued data will accumulate? HiveMQ’s pages we read do not size it. Measure it in a test.
  4. Do all nodes share a failure domain? Three nodes on one hypervisor host, one switch or one power feed are one node in practice.
  5. Is discovery allowed on the target network? Multicast often is not.
  6. What is the recovery plan if more nodes fail than the replica count? Test the Recovery Tool and a backup import before go-live.

Stretching a HiveMQ cluster over a WAN

The current HiveMQ cluster documentation we read does not address WAN links or latency between nodes. We found no HiveMQ statement that a stretched cluster is supported, and none that it is prohibited. We therefore cannot say it works, and we would get HiveMQ’s position in writing with latency bounds before designing one.

The documented multi-site tool is bridging. The Enterprise Bridge extension lets a regional cluster stream chosen topics to a central broker, with the same bridge configuration on every node, and HiveMQ Edge bridges do the same at the plant edge. The trade-off is that each site keeps its own state and a partition between sites does not stall the plant. See also the multi-site architecture page.

Where it gets hard

  • Silent shared failure domains make a cluster look redundant when it is not.
  • Unknown partition behaviour: conflict resolution after a merge is not explained in the documentation we read.
  • Capacity after loss: the remaining nodes must carry the load plus redistribution.
  • Version drift across nodes during long rolling upgrades.

What we do here

We design MQTT and Unified Namespace architectures and integrate brokers with PLCs, SCADA, historians and enterprise systems as part of IT/OT projects. We are independent of HiveMQ: we have no commercial relationship with the company and do not resell its products. When a clustered broker is proposed, we review the failure-domain layout and write a test plan for node loss and reconnect. Our OT network segmentation guide covers where such nodes belong.

Parent: HiveMQ Platform. Technology hub: HiveMQ. Sibling: deployment and Kubernetes.

Frequently asked questions

How does a HiveMQ cluster keep data when a node fails?

HiveMQ's documentation says persistent data is replicated, with a default replica count of 2: one original and one copy. If one node fails, the copy on another node is used. If more nodes fail permanently than the replica count, persistent data can become unavailable, and recovery needs the Recovery Tool and a backup import.

Is a HiveMQ cluster active-active or active-passive?

HiveMQ describes a masterless design in which every node is equal and the cluster acts as one logical broker. Clients can connect to any node. That is closer to active-active than to a primary and standby pair, but the documentation does not use either label.

Can a HiveMQ cluster span two sites over a WAN?

HiveMQ's documentation we read neither says it is supported nor prohibits it. The cluster page does not address latency or distance between nodes. HiveMQ documents bridging, where a broker at each site forwards chosen topics, as the multi-site tool. Ask HiveMQ in writing before designing a stretched cluster.

What does HiveMQ overload protection do?

Each node computes an overload level every 100 milliseconds and all nodes apply the highest. Each client has a budget of 100 credits that publish, subscribe and unsubscribe packets spend. At zero credits the broker stops reading that client's TCP socket, which applies backpressure. It is on by default and HiveMQ advises against disabling it.

How many nodes should a HiveMQ cluster have?

HiveMQ's cluster page we read does not state a minimum node count. The replica count cannot exceed the node count, and the default of 2 needs at least two nodes. We would ask how many node losses the plant must survive, then add the capacity to carry the load on the remaining nodes.

References and further reading

  1. HiveMQ cluster documentation · HiveMQReplication, discovery, transport, failure detection and recovery.
  2. HiveMQ overload protection · HiveMQThe credit system and backpressure.
  3. HiveMQ Enterprise Bridge extension · HiveMQThe documented multi-site tool.
  4. What's new in HiveMQ 4.57 · HiveMQFix for clusters that stopped accepting nodes after a failed join.
  5. HiveMQ Enterprise MQTT Broker user guide · HiveMQ

← HiveMQ Platform

Have a project that needs technical ownership?

Send us the situation. If it is not something we should take on, we will say so.

The Plant-Side Brief

The weekly brief for the people who own a plant’s control systems.

One email every Wednesday for engineering and operations leaders responsible for controls, SCADA, MES and OT networks. Skim the top in two minutes; read the Deep Dive when you have fifteen.

  • One modernization problem, worked through to cost, risk and a schedule you can defend. The Deep Dive.
  • End-of-support dates before they reach your plant Windows, servers, controllers and HMI software. Lifecycle Watch.
  • A checklist your engineers can run that week not a framework to admire. Field Kit.
  • Every number sourced, no vendor agenda we are paid by plants, never by vendors.