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 (also known as Log Retrieval) 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. Common triggers include a client process crash or forced termination (for example, `kill -9`), or an internal MQTT SDK exception that closes the TCP connection abnormally. Check the client logs to confirm the disconnection timestamp and whether the client process exited abnormally.
`Socket IOException`	Connection closed. Network jitter or packet loss broke the TCP connection. Common triggers include a brief interruption of the client's local network, or a firewall or proxy server that blocks the MQTT connection. Check the client's network connectivity and confirm that firewall and security group rules allow traffic on the MQTT ports (1883 for TCP and 8883 for TLS).
`invalid param`	Connection closed. The request contained invalid parameters.
`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 empty query results

An empty query result means the device has no connection records within the selected time range. Troubleshoot the issue using the following steps:

Confirm whether the device has ever initiated a connection request — Subscribe to online/offline notifications through rule management to monitor the device's connection status in real time.
Check the network on the device side — Verify that the device can access the ApsaraMQ for MQTT endpoint domain, and check whether firewall rules allow the connection.
Check the authentication information — Verify that the token or certificate has not expired or been misconfigured.
Check the reconnection logic — Verify the device's reconnection interval and maximum retry count.
Confirm the time range — The maximum query time span is one day. Make sure the selected time range covers the period when the device may have connected.

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, including an internal MQTT SDK exception.
The client process was forcefully killed, for example, by running kill -9.

Inspect the client application logs to confirm the disconnection timestamp and whether the client process exited abnormally.

Note

Network-level interruptions, such as a transient network outage or a firewall that blocks the connection, are reported separately. See the Network jitter or packet loss section below.

Network jitter or packet loss

Indicator: Socket IOException

Network jitter or packet loss between the client and the broker broke the TCP connection. Possible causes:

A transient network outage on the client side, such as an operating system-level network interruption caused by a NIC failure.
A firewall or proxy server that blocks the MQTT connection.

Verify that the client can reach the ApsaraMQ for MQTT endpoint, and confirm that firewall and security group rules allow traffic on the MQTT ports (1883 for TCP and 8883 for TLS).

Invalid request parameter

Indicator: invalid param

The connection was closed because the client sent a request that contains an invalid parameter. Check the connection parameters on the client against the protocol requirements and correct any invalid values.

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