Use the device trace query feature of ApsaraMQ for MQTT to troubleshoot device connection issues - ApsaraMQ for MQTT

When a device disconnects unexpectedly, use Device Trace Query to review its connection history. The query results show each connect, disconnect, and close event with a detailed reason, helping you pinpoint why the connection dropped.

Prerequisites

Before you begin, make sure that you have:

A running ApsaraMQ for MQTT instance
The Group ID and Device ID of the target device

Query device connection events

Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.
In the top navigation bar, select the region where your instance resides. Click the instance name to open the Instance Details page.
Find the instance that you want to manage. In the Actions column, choose More > Device Trace Query.
On the Device Trace Query page, specify the Group ID, Device ID, and Time Range, then click Search.
Note
The maximum query time span is one day.

Query results

The query returns a table with the following columns:

Column	Description
Channel ID	The connection ID.
Device Action	The type of connection event. See the Device actions section below.
Action Description	The reason or outcome of the event. See the Action descriptions section below.
Time	The timestamp when the event occurred.

Device actions

Each device action represents a stage in the MQTT connection lifecycle:

Value	Meaning	Lifecycle stage
`connect`	The client sent a CONNECT request to the broker.	Connection initiation
`close`	The TCP connection was closed.	Connection termination (passive)
`disconnect`	The client sent a DISCONNECT request to the broker.	Connection termination (active)

Action descriptions

Each action description explains why the connection state changed:

Value	Meaning
`accepted`	The broker accepted the client's connection request.
`not authorized`	Connection closed. The client failed permission verification to access the instance.
`topic auth failed`	Connection closed. The client failed permission verification to access topics.
`clientId conflict`	Connection closed due to a conflict in the client ID.
`no heart`	Connection closed. The broker detected no heartbeat from the client.
`closed by client`	Connection closed due to a client-side exception. The client did not send a DISCONNECT packet.
`disconnected by client`	The client initiated a graceful disconnection by sending a DISCONNECT packet.
`ServerShutdown`	Connection closed. The broker was upgraded or went offline for maintenance.

Troubleshoot disconnections

Use the Action Description value to identify the root cause of a disconnection:

Permission verification failure

Indicators: not authorized, topic auth failed

Verify that the client credentials are correct and that the client has the required permissions for both the instance and the target topics. Check the following:

The client credentials are valid and not expired.
Topic permissions are granted for the specific topics the client subscribes to or publishes to.

Client ID conflict

Indicator: clientId conflict

Two clients sharing the same client ID cannot maintain simultaneous connections. To resolve this:

Make sure each client uses a unique client ID.
Check for duplicate deployments or misconfigured device provisioning that may assign the same ID to multiple devices.

Heartbeat timeout

Indicator: no heart

The broker closes the connection if it receives no heartbeat from the client. Possible causes:

Network instability prevents heartbeat packets from reaching the broker.
The client process is blocked or overloaded, preventing timely heartbeat transmission.

Unexpected client-side closure

Indicator: closed by client

The TCP connection was terminated without the client sending a DISCONNECT packet. This typically indicates:

A crash or unhandled exception in the client application.
An operating system-level network interruption (e.g., a firewall rule change or NIC failure).
The client process was forcefully killed.

Inspect the client application logs and system-level network logs to identify the cause.

Broker maintenance

Indicator: ServerShutdown

No action required. The broker closed connections during a scheduled upgrade or maintenance window.

ApsaraMQ for MQTT:Query the connection history of a device