By default, ApsaraMQ for MQTT keeps a client's subscriptions active after it disconnects and delivers queued offline messages when the client reconnects. If your messages have freshness requirements or you need to retire inactive subscribers, enable subscription cleanup to automatically remove subscriptions after a client has been offline for a specified period.
How subscription cleanup works
ApsaraMQ for MQTT tracks each client's last heartbeat. With automatic subscription cleanup enabled for a topic, ApsaraMQ for MQTT compares the current time against the client's last heartbeat. If the offline duration meets or exceeds the configured Cleanup Cycle, the system deletes the subscription between that client and the topic.
After a subscription is cleared:
The client stops receiving new offline messages from that topic.
The client can still receive offline messages that were generated *before* the cleanup and remain within their validity period.
Offline message delivery also depends on the QoS and cleanSession parameters. For details, see Terms.
Subscription changes affect instance billing. For details, see Billing overview.
Configure subscription cleanup
Procedure
Enabling subscription cleanup prevents clients from receiving offline messages. Proceed with caution.
Log on to the ApsaraMQ for MQTT console and click Instances in the left-side navigation pane.
In the top navigation bar, select a region. On the Instances page, click the instance ID to open the Instance Details page.
In the left-side navigation pane, click Topics. Find the target topic and choose in the Actions column.
In the Configure Automatic Cleanup Cycle panel, configure the following settings and click OK.
Setting Description Enable Automatic Subscription Cleanup Set to Yes to activate automatic cleanup, or No to keep subscriptions persistent. Cleanup Cycle The offline threshold for subscription removal. A subscription is cleared when the time since the client's last heartbeat meets or exceeds this value.
Result
After saving, confirm the cleanup cycle in the Subscription Cleanup Cycle column of the topic list.
Unsubscribe from a topic on the client
MQTT does not clear existing subscriptions automatically while a client is online. To switch topics, call the SDK unsubscribe method to remove the old subscription before you subscribe to the new topic.
Subscription cleanup in the console applies only to offline clients: a subscription is removed after the client stays offline longer than the configured cleanup cycle. It does not apply to topic switching on an online client.
Java SDK sample:
MqttClient mqttClient = new MqttClient("tcp://" + endPoint + ":1883", clientId, new MemoryPersistence());
mqttClient.connect(options);
// Subscribe to topicA
mqttClient.subscribe("topicA", 1);
// Before switching to topicB, cancel the topicA subscription
mqttClient.unsubscribe("topicA");
// Then subscribe to topicB
mqttClient.subscribe("topicB", 1);Call unsubscribe on the old topic first, then subscribe to the new topic, so that the two subscriptions are never active at the same time.