Devices Losing First Message After Wakeup

Overview

This article addresses an issue where IoT devices with sleep/wake cycles fail to receive the first message published to their topic immediately after waking up and reconnecting to the HiveMQ broker.

Issue Description

Symptoms:

Device wakes from sleep and connects to HiveMQ
Device subscribes to its topic
First message published to the topic is not received by the device
Subsequent messages are received normally

Common Scenario:
This issue typically occurs with battery-powered IoT devices that enter sleep mode to conserve power and periodically wake to check for new data.

Root Cause Analysis

The most common cause is the absence or expiration of a retained message on the subscribed topic. In MQTT, a device waking from sleep will only receive a message immediately upon subscribing if an active retained message exists on that topic(1)(https://docs.hivemq.com/hivemq/latest/control-center/trace-recordings.html).

Key factors:

Publisher not setting retain = true when publishing messages
Message Expiry Interval causing messages to expire during the device's sleep cycle
No retained message configured on the topic

Diagnostic Steps

Step 1: Verify Client ID and Connection Behavior

Identify the exact client ID of the affected device
Check broker logs for disconnect reasons, particularly "Client was idle for too long" which indicates the client exceeded 1.5x the keepAlive value

Step 2: Check for Retained Messages

You can verify if a retained message exists on the topic using MQTT CLI or another MQTT client:

To Subscribe and Check for Retained Message:


mqtt sub -t 'your/topic' -h 'your-broker-host' -J -d

If a retained message is active, you will receive it instantly upon connection.

To Publish a Retained Message:


mqtt pub -t 'your/topic' -m 'your message' -r -h 'your-broker-host'

Note: The -r flag sets the retain flag to true.

Step 3: Create a Trace Recording

For clusters with Control Center access, create a trace recording to capture the full message flow(1)(https://docs.hivemq.com/hivemq/latest/control-center/trace-recordings.html):

Navigate to the Trace Recordings view in HiveMQ Control Center
Click to add a new trace recording
Configure the recording:
- Name: Use a descriptive name (e.g., device-wakeup-test)
- Start: Set to the time window when the device will wake
- End: Set to cover the full wake/publish cycle
- Client Identifier Filter: Enter the device's client ID
- MQTT Packets: Select all packet types, particularly CONNECT, SUBSCRIBE, and PUBLISH
Start the recording
Trigger the device wake cycle
Stop and download the recording(1)(https://docs.hivemq.com/hivemq/latest/control-center/trace-recordings.html)

Step 4: Analyze Trace Recording

Review the downloaded .trace file for:

CONNECT packet from the device
SUBSCRIBE packet to the expected topic
Presence or absence of PUBLISH packet immediately after SUBSCRIBE
Any DISCONNECT events with reason codes

Resolution Steps

Solution 1: Enable Retained Messages

Ensure the publisher sends messages with the retain flag set to true:

Publisher Configuration:

Set retain = true in PUBLISH packets
Verify retained message appears in Control Center under the topic

Solution 2: Configure Message Expiry

If using MQTT 5, configure an appropriate Message Expiry Interval that exceeds the device's maximum sleep duration(2)(https://docs.hivemq.com/hivemq/latest/user-guide/configuration.html).

In HiveMQ config.xml:


<hivemq>
    <mqtt>
        <message-expiry>
            <max-interval>86400</max-interval>
        </message-expiry>
    </mqtt>
</hivemq>

This example sets message expiry to 24 hours (86400 seconds)(2)(https://docs.hivemq.com/hivemq/latest/user-guide/configuration.html).

Solution 3: Adjust Session Expiry

Ensure the session expiry interval exceeds the device's sleep duration(2)(https://docs.hivemq.com/hivemq/latest/user-guide/configuration.html):


<hivemq>
    <mqtt>
        <session-expiry>
            <max-interval>86400</max-interval>
        </session-expiry>
    </mqtt>
</hivemq>

Solution 4: Verify Subscription Timing

Confirm that messages are sent after the client subscribes to the topic. The broker flushes messages to clients when the client subscribes to the topic, not merely when it connects to the session.

Prevention and Best Practices

Always use retained messages for topics where sleeping devices need to receive the latest state immediately upon waking
Set appropriate Message Expiry Intervals that account for maximum expected sleep durations
Configure Session Expiry to be longer than device sleep cycles
Monitor keepAlive settings to prevent premature disconnections
Implement trace recordings during testing phases to validate message delivery patterns
Document client IDs accurately for troubleshooting purposes

Limitations for Older Cluster Architectures

For clusters running on older-generation architecture without Control Center or REST API enabled:

Trace recordings cannot be initiated remotely by support teams
Manual testing with MQTT CLI is required
Consider cluster migration to access modern diagnostic tools

Additional Notes

Message Delivery Timing:
The broker delivers queued messages when the client subscribes to a topic, not when it initially connects to the session. Ensure your device application subscribes to topics immediately after establishing the connection.

Trace Recording Storage:
All trace recording log files are stored as trace-recording-name.trace in the hivemq/log/recordings folder of the HiveMQ instance(1)(https://docs.hivemq.com/hivemq/latest/control-center/trace-recordings.html).

—