MQTT Node Cannot Join the Cluster - Troubleshooting Guide

Issue Overview

When HiveMQ nodes fail to join a cluster, it typically indicates problems with cluster configuration, network connectivity, or synchronization processes (https://docs.hivemq.com/hivemq/latest/user-guide/cluster.html).

Common Causes

Incorrect cluster discovery configuration
Network connectivity issues between nodes
Firewall blocking cluster transport ports
Incompatible transport and discovery mechanisms
Node synchronization failures

Prerequisites for Cluster Formation

To form a HiveMQ cluster, the following features must be enabled on each broker node:

Clustering
Cluster discovery
Cluster transport

Diagnostic Steps

1. Check Node Synchronization Status

Monitor HiveMQ log files for synchronization messages. Wait for the log statement:

INFO - Started HiveMQ in …

which indicates successful node synchronization with the cluster.

During synchronization, you should see these log entries:

Starting cluster join process. This may take a while. Please do not shut down HiveMQ.
Cluster join process is still ongoing. Please do not shut down HiveMQ.
Finished cluster join process successfully.

2. Verify Cluster Configuration

Ensure your cluster configuration includes discovery


<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <cluster>
        <enabled>true</enabled>
        <transport>
           <tcp>
                <bind-address>192.168.1.1</bind-address>
                <bind-port>7800</bind-port>
           </tcp>
        </transport>
        <discovery>
            <static>
                <node>
                    <host>192.168.1.1</host>
                    <port>7800</port>
                </node>
                <node>
                    <host>192.168.1.2</host>
                    <port>7800</port>
                </node>
            </static>
        </discovery>
    </cluster>
</hivemq>

3. Validate Discovery Mechanism Compatibility

Verify that your chosen discovery mechanism is compatible with your transport protocol:

Discovery Method	UDP Transport	TCP Transport	Dynamic

Discovery Method	UDP Transport	TCP Transport	Dynamic
Static	✓	✓	✗
Multicast	✓	✗	✓
Broadcast	✗	✓	✓
Extension	✓	✓	✓

Resolution Steps

For Static Discovery Issues

Provide a full list of all HiveMQ broker nodes to each individual node for increased failure resistance and stability
Verify IP addresses and ports are correct in the static node list

For Multicast Discovery Issues

Common obstacles include:

Firewall preventing clustering (disable for testing)
Cluster nodes not in the same network
Multicast not enabled on the machine
Switch/router not supporting multicast
Cloud providers (including AWS) not permitting IP multicast.

For Network Connectivity Issues

Ensure cluster transport ports are open between nodes.
Verify network connectivity between all cluster nodes.
Check firewall rules and security groups.

Prevention Strategies

Use TCP transport as the recommended protocol for production clusters.
Implement proper network security while ensuring cluster ports remain accessible.
Test cluster configuration in development environments before production deployment
For cloud deployments, avoid UDP multicast and use static or extension discovery instead

Additional Resources

For more detailed cluster configuration guidance, see: