Troubleshooting MQTT Client Connection and Subscription Failures

Problem

This article provides troubleshooting steps when MQTT clients are unable to connect to the MQTT broker and fail to subscribe to topics(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues). Connection failures can occur due to various reasons, including authentication issues, network problems, or configuration errors(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues).

Solution

Step 1: Enable Debug Logging

To capture detailed information about client connection attempts, enable DEBUG level logging on the HiveMQ broker(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues).

You can set the environment variable or modify the configuration file(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues):

HIVEMQ_LOG_LEVEL=DEBUG

Alternatively, modify /opt/hivemq/conf/logback.xml(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues).

Note: DEBUG logging generates significantly more disk usage compared to the default INFO log level(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues).

Step 2: Check HiveMQ Logs

Inspect the HiveMQ logs located at /opt/hivemq/log/hivemq*.log for any errors related to the specific client IDs that are experiencing connection issues(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues).

Step 3: Use Trace Recording

If you have identified the problematic client IDs, consider using HiveMQ's Trace Recording feature to capture all MQTT packets (CONNECT, DISCONNECT, SUBSCRIBE, etc.) for these clients(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues). This will provide deeper insights into their connection lifecycle(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues).

Step 4: Verify Authentication Credentials

Connection failures with error code BAD_USER_NAME_OR_PASSWORD indicate authentication issues(2)(https://github.com/hivemq/hivemq-mqtt-client/issues/641). When connecting with username and password authentication, ensure credentials are properly configured(2)(https://github.com/hivemq/hivemq-mqtt-client/issues/641).

For MQTT 5 clients using simple authentication, verify the username and password are correctly set(2)(https://github.com/hivemq/hivemq-mqtt-client/issues/641):

final Mqtt5BlockingClient client = Mqtt5Client.builder()
    .identifier(getClientId())
    .serverHost(HOST)
    .serverPort(PORT)
    .simpleAuth()
        .username(USERNAME)
        .password(ByteBuffer.wrap(PASSWORD.getBytes(StandardCharsets.UTF_8)))
    .applySimpleAuth()

Step 5: Configure Message Handlers Before Subscribing

Set your message handlers before subscribing to topics to ensure messages are properly received(3)(https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/subscribing).

client.OnMessageReceived += (sender, args) =>
{
    Console.WriteLine("Message Received: {}", args.PublishMessage.PayloadAsString)
};

await client.ConnectAsync();

Step 6: Verify Connection Parameters

When establishing connections, ensure proper configuration of connection parameters(4)(https://www.hivemq.com/blog/mqtt-brokers-beginners-guide):

Client Initialization: Initialize the MQTT library with the correct broker address and port(4)(https://www.hivemq.com/blog/mqtt-brokers-beginners-guide)
Connection to broker: Establish TCP/IP connection (default port 1883, or 8883 for TLS/SSL)(4)(https://www.hivemq.com/blog/mqtt-brokers-beginners-guide)
Connect packet: Send CONNECT packet with client ID, connection flags, and settings(4)(https://www.hivemq.com/blog/mqtt-brokers-beginners-guide)
Keep-Alive: Maintain connection with periodic Ping packets(4)(https://www.hivemq.com/blog/mqtt-brokers-beginners-guide)

Step 7: Check Automatic Reconnection Configuration

If clients are not reconnecting after disconnection, verify that automatic reconnection is properly configured(5)(https://github.com/hivemq/hivemq-mqtt-client/issues/747):

Mqtt5AsyncClient client = MqttClient.builder()
    .useMqttVersion5()
    .serverHost(props.getBrokerUrl())
    .serverPort(props.getPort())
    .identifier(clientId)
    .automaticReconnectWithDefaultConfig()
    .addConnectedListener(callback)
    .addDisconnectedListener(callback)
    .buildAsync();

Important Notes

Ensure DEBUG logging and Trace Recording are disabled once troubleshooting is complete, as they increase disk usage consumption(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues)
Authentication and authorization are handled by the broker based on credentials provided by the client(4)(https://www.hivemq.com/blog/mqtt-brokers-beginners-guide)
The broker maintains session data for all connected clients, including subscriptions and missed messages for persistent sessions(4)(https://www.hivemq.com/blog/mqtt-brokers-beginners-guide)

Prevention and Best Practices

To prevent connection and subscription issues:

Implement proper error handling and logging in client applications
Use persistent sessions appropriately for reliable message delivery(6)(https://hivemq.atlassian.net/wiki/spaces/HCSP/pages/2700640571/How+to+test+Persistent+Session+Management+with+MQTT+Brokers)
Configure automatic reconnection with appropriate settings(5)(https://github.com/hivemq/hivemq-mqtt-client/issues/747)
Validate authentication credentials before deployment
Monitor broker logs regularly for connection patterns and errors(1)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3163914241/Troubleshooting+MQTT+Client+Connection+Issues)
Test connection scenarios in development before production deployment