Clearing Queued Messages in HiveMQ Cloud

Overview

This knowledge base article addresses the issue of excessive queued messages accumulating in HiveMQ Cloud and provides steps to identify, resolve, and prevent recurrence of this issue.

Issue Description

A large number of messages (20 million+) accumulated in the message queue due to a client-side bug where clients were publishing with an incorrect protocol. This resulted in messages being queued for offline or slow-consuming clients.

Root Cause

The root cause was identified as a client-side bug that caused improper protocol usage during message publishing. This led to messages accumulating in client queues rather than being properly consumed.

Understanding Message Queuing in HiveMQ

Message queueing occurs in two primary scenarios(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html):

Messages published on topics for which an offline client with an existing session has a subscription
An online client cannot consume messages at the same speed as the broker sends them

The current and maximum number of messages in the message queue can be viewed in the Control Center(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html):

Current: Shows the number of messages in the message queue of the client at the time that the snapshot is taken
Maximum: Shows the queue size limit that is set for the client

Identifying Queued Messages

Using HiveMQ Control Center

Navigate to Clients in the Control Center(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Select Refresh Snapshot to create a fresh snapshot of all MQTT sessions(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Review the Queue Size column which shows current and maximum queue sizes(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Sort by queue size to identify clients with high message counts(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Select a client identifier to view detailed client information(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)

The Clients overview displays the following information(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html):

Client ID: The unique identifier of the client
Connected: Shows whether a client is currently connected
Queue Size: Current and maximum number of messages in the message queue
Username: The username of the client
IP Address: The IP address of the client

Resolution Options

Option 1: Client Reconnection with Clean Session

Have affected clients reconnect with clean_start=1. When a client connects with a non-persistent session, the broker does not save any subscription information when the client disconnects(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html).

Steps:

Configure clients to reconnect with clean_start=1
The broker will clear the session and all associated queued messages
If message persistence is required, clients can reconnect with clean_start=0 after queue clearance

Option 2: Manual Client Session Invalidation

For HiveMQ Cloud Enterprise deployments with large numbers of affected clients, HiveMQ Support can assist with session invalidation using API-based scripts.

Process:

Identify all clients with excessive queue sizes (e.g., 10,000+ messages)
Create an API token for script execution
Execute invalidation scripts while monitoring cluster resource metrics
Verify queue clearance in Control Center
Delete API token after completion

Option 3: Individual Client Disconnect and Reconnect

For smaller numbers of affected clients:

Locate the client with a high message queue in Control Center → Clients → Queue Size(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Click on the client to view details(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Disconnect the client (ensure the client is programmed to reconnect automatically)
Monitor the same client in Control Center → Clients → Queue Size(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Verify that reconnection clears the message queue and that the metric is not increasing

Monitoring and Verification

Control Center Metrics

Monitor the following metrics in the Control Center(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html):

Queued Messages: The current number of queued messages and replicas stored in the cluster(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)
Connections: The current total number of active connections for all cluster nodes(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)
Inbound Publish Rate: The current total number of incoming PUBLISH packets per second(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)
Outbound Publish Rate: The current total number of outgoing PUBLISH packets per second(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)

Dropped Messages Analysis

Review the Dropped Messages view to identify any message delivery issues(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html):

Client Message Queue Full: Client's message queue was full when another message arrived(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)
QoS 0 Memory Exceeded: Broker-wide memory for queueing QoS 0 messages has been exceeded(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)
QoS 0 Channel Not Writable: QoS 0 message could not be delivered because it was impossible to write to the client socket(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)

Prevention Strategies

Client-Side Measures

Ensure clients use the correct MQTT protocol version
Implement proper error handling and reconnection logic
Configure clients to consume messages at an appropriate rate
Use clean_start=1 when persistent sessions are not required

Broker-Side Configuration

Configure appropriate queue limits in the HiveMQ configuration(3)(https://docs.hivemq.com/hivemq/latest/user-guide/configuration.html):


<hivemq>
    <mqtt>
        <queued-messages>
            <max-queue-size>1000</max-queue-size>
            <strategy>discard-oldest</strategy>
        </queued-messages>
    </mqtt>
</hivemq>

Monitoring and Alerting

Regularly review queue size metrics in Control Center(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
Set up alerts for abnormal queue growth
Monitor dropped messages by reason(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)
Review client event history for connection issues(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)

Additional Resources

HiveMQ Control Center documentation for client management(1)(https://docs.hivemq.com/hivemq/latest/control-center/information.html)
HiveMQ configuration options for message queuing(3)(https://docs.hivemq.com/hivemq/latest/user-guide/configuration.html)
Analytics and monitoring capabilities(2)(https://docs.hivemq.com/hivemq/latest/control-center/analytic.html)

Support Escalation

For large-scale queue cleanup operations affecting thousands of clients, contact HiveMQ Support for assistance with:

API-based session invalidation scripts
Cluster resource monitoring during cleanup
Custom cleanup strategies for specific deployment scenarios

—

Note: This article is based on a production incident where 20 million queued messages were successfully cleared through coordinated session invalidation of 760+ affected clients.