Mass Client Unsubscription Alert

The Mass Client Unsubscription alert indicates that many clients unsubscribed from topics within a short period. It is triggered only when there were at least 100 subscriptions 30 minutes earlier and the percentage of removed subscriptions exceeds the configured threshold.

This condition may prevent messages from reaching subscribers. Common causes include unexpected client disconnections, clients that fail to resubscribe after reconnecting, and defects in client unsubscription logic.

Unexpected Client Disconnections

Symptom

Network instability, a regional carrier failure, or network maintenance interrupts many EMQX Cloud client connections within a short period. If the clients do not use persistent sessions and automatic reconnection correctly, their subscriptions may be removed and trigger the alert.

On the deployment Monitor page, both the connection count and subscription count drop sharply within a short period.

Common Causes

• Network instability or a regional outage disconnects many clients.
• Clients do not use persistent sessions, so subscriptions are not retained after disconnection.
• Clients do not implement automatic reconnection correctly.

Resolution

• Configure persistent sessions and reliable automatic reconnection so that clients reconnect promptly and retain their subscriptions.
• When persistent sessions are enabled, use a stable clientid so that reconnecting clients resume the same session and subscriptions.

Client SDK or API Calls

Symptom

The subscription count falls sharply while the connection count remains relatively stable. Clients remain online, but subscriptions are actively removed. A client SDK defect or an incorrect application API call, such as a batch call to unsubscribe, may be responsible.

The deployment Monitor page shows a sharp increase in unsubscriptions while connections remain stable. Client logs from the same period show batch unsubscribe calls or abnormal reconnection behavior.

Common Causes

• Client logic subscribes and then unsubscribes without resubscribing.
• A third-party SDK has a compatibility issue with Clean Session or persistent session settings.
• Application code mistakenly calls a batch unsubscribe API and removes many subscriptions.

Resolution

• Check client logic for subscribe-unsubscribe sequences that do not resubscribe.
• Upgrade third-party SDKs to the latest version and test their Clean Session and persistent session behavior.
• Avoid unnecessary batch unsubscribe operations. If the operation is required, make sure the client subsequently performs resubscribe correctly.

Troubleshooting

1. Log in to the EMQX Cloud Console.

2. Go to Alerts -> Alert List. Check for a Mass Client Unsubscription alert and review its trigger period and scope.

   

3. Go to Monitor -> Metrics -> Timeline -> Subscriptions. Verify whether the subscription count fell from at least 100 within the past 30 minutes and whether the decline exceeded the configured threshold.

4. Compare the trigger time with client logs and application activity to determine whether unexpected disconnections or explicit unsubscribe calls caused the decline.

Monitoring and Statistics

Go to Metrics -> Timeline -> Subscriptions to monitor the overall subscription trend and determine whether the unsubscription rate is recovering.

Track Client Unsubscription Events

• EMQX Cloud does not retain historical client subscription changes. To track unsubscriptions over time, create a data integration rule for the $events/session_unsubscribed event topic and forward or store the events. For example:

  SELECT
      *
  FROM
      "$events/session_unsubscribed"

• You can filter fields such as clientid and topic. For details, see SQL Data Sources and Fields.

• This event is emitted only when a client explicitly unsubscribes. It is not emitted when a subscription is removed because the client disconnected.