Client Event

フォーカスモード

フォントサイズ

最終更新日: 2026-01-30 14:59:41

Introduction
In IoT services, devices operate in complex network environments (weak signals, power outages, mobile network switching), where "offline" or "connection failure" represent the most frequent issues. Client events refer to a series of state changes and interaction notifications triggered by clients during MQTT protocol communication. By tracking system events, users can promptly troubleshoot and analyze problems to quickly resolve service issues, thereby ensuring system stability.
Obtain Client Events
It is recommended that you obtain client events through one of the following two methods. For detailed field definitions and full content of client events, see Query Client Events.
Method 1: Console Query
1. Log in to the MQTT Console.
2. Click Resource > Cluster in the left sidebar. After selecting a region, click the "ID" of the target cluster to enter the cluster basic information page.
3. In the left tab bar, select Client to go to the specific client details page. You can then scroll down to view client events.
﻿
Method 2: Subscribe to System Topics
Subscribe to system event topics, such as $event/client_connected (online), $events/session_subscribed (subscription), or subscribe to all events $events/#, to receive event messages containing detailed information. For specifics, refer to the Event Topics section in the Query Client Events documentation.
Best Practices
Scenario 1: Client Connection Failure Troubleshooting
Device logs indicate connection failure or disconnection, or the console's client list status shows "offline".
Troubleshooting Steps
Log in to the MQTT Console > Client > Search for the client by Client ID, and click View Details.
Filter the event records for this client.
Focus on the client_disconnected event's reason field. For specific definitions of disconnection reasons and resolution suggestions, refer to the following Common Disconnection Reasons Reference Table.
Scenario 2 Client Takeover
Typical Manifestations
When the network environment is normal, the device continuously and frequently reconnects. Connected and Disconnected messages appear intensively in the logs, and the device fails to remain online stably.
Note:
Takeover (takeover/mutual kick-out) refers to the behavior where when a client initiates a connection using an already occupied Client ID, the Broker forcibly disconnects the existing connection and establishes a new one. The MQTT protocol stipulates that only one connection can exist for the same Client ID at any given time.
Troubleshooting Steps
View the event timeline in the console.
If frequent alternating occurrences of client_connected and client_disconnected are observed.
Check the reason field in the client_disconnected event. If the reason is taken over, this is one of the most typical causes of client connection jitter, indicating that the current client was kicked offline by another device using the same Client ID.
Solution
Ensure that each device's Client ID is globally unique.
Check whether any old test scripts have not been stopped.
Note:
When troubleshooting of Takeover issues is performed, not all reason: taken over indicate a fault. If it is a sporadic occurrence and typically happens after device network fluctuations subside, it may be MQTT's Self-Repair behavior in weak network environments, requiring no additional intervention.
Scenario 3: Troubleshooting Undelivered Messages
Client events are primarily used for diagnosing connectivity issues. If you encounter a situation where a device is online but unable to send or receive messages, it usually requires joint troubleshooting with Message Tracing.
Determine Online Status Using Events: Obtain the message delivery timestamp via Message Tracing, check if there is a client_disconnected event at that time, and confirm whether the device experienced a brief disconnection.
Determine Subscription Behavior Using Events: Check whether there is a session_subscribed event to confirm whether the device has successfully subscribed to the target Topic.
Regarding detailed troubleshooting steps for consumption process issues such as "message loss" and "ACK unacknowledged", please refer to Message Tracing.
Common Disconnection Reasons Reference Table
Disconnection Reason
Semantics
Recommended Solution
normal
The server received the DISCONNECT message and disconnected normally.
Normal event. Confirm whether the client-initiated disconnection is expected by business logic (for example, the client actively exits upon task completion).
takeovered
The client was disconnected by a device with the same client ID.
Client ID conflict. Check the client ID generation policy to ensure each online device has a unique client ID.
(If it is an occasional single occurrence, it may be an automatic recovery after network fluctuation, and no action is required.)
kicked
The client was forced to log out by management.
Administrative action. Please check the management console or API call logs of the MQTT service to confirm which administrator or automated policy performed the force-logout action and why.
keepalive_timeout
The MQTT Broker node did not receive an interactive message from the client within 1.5 times the keep-alive period.
Network or client issue.
1.  Check whether the device network connection is stable.
2.  Check whether the device CPU/memory load is too high, resulting in failure to send heartbeat packets in time.
3.  In a weak network environment, you may appropriately increase the keep-alive value.
not_authenticated
Unauthenticated, similar to HTTP status code 401.
Authentication information error. Check whether the username, password, certificate, or Token configured for the client is correct and whether it matches the server-side configuration.
not_authorized
Unauthorized, similar to HTTP status code 403.
Insufficient permissions. The client is authenticated but lacks permission to connect or perform operations (such as publishing/subscribing to specific topics). Check the ACL policy configuration and grant necessary permissions to this client.
tcp_closed
TCP connection closed.
Network layer disconnected. Possible causes include device network interruption, NAT Gateway timeout, or firewall policy blocking.
ping_without_connect
The client sent a PING before sending the CONNECT packet. 
Client SDK/firmware Bug. Check and fix the client MQTT protocol implementation code to ensure strict adherence to the connection establishment sequence: CONNECT -> other packets.
authentication_expired
Authentication failed. JWT/SAS tokens have expired.
Credentials expired. The client program should have the capability to refresh Token.
too_many_connection
Exceeding the maximum cluster/node connections.
Server-side capacity issue.
1. Contact Us to upgrade your service specifications or increase the maximum connection limit.
2. Troubleshoot whether client-side exceptions (such as code bugs) are causing the creation of a large number of invalid connections.
go_away
MQTT Broker node restart, graceful shutdown.
Usually caused by server-side upgrades or maintenance. The client should implement an automatic reconnection mechanism to automatically reconnect after the server recovers.
client_id_too_long
Client ID exceeds the maximum limit.
Client ID exceeds the maximum length. Check the ID length (the MQTT protocol's inherent limit of 23 characters) and modify the client ID generation logic.
client_id_required
Persistent session connection lacks the required client ID field.
Client protocol error. When CleanSession=false, the client ID cannot be empty. Please fix the client logic: either provide an ID or set CleanSession to true.
client_id_invalid
Client ID contains invalid characters. For details, see Spec 3.1.3.1.
Client ID is non-compliant. Client ID can only contain [0-9a-zA-Z] characters. Please modify the client ID generation logic to remove or replace invalid characters.
bad_will_message
Illegal will message.
Will message configuration error. Check the will message (Will Message) set by the client, ensure its topic (Topic) and payload (Payload) formats are correct, and verify that the client has permission to publish messages to the specified will topic.
server_internal_error
Internal server error.
Server issue. Please contact us and provide relevant information (such as timestamp, instance ID, and client ID) to troubleshoot server issues.

ヘルプとサポート

この記事はお役に立ちましたか？

営業担当者にお問い合わせいただくかチケットを提出してサポートを求めることができます。

フィードバック

tencent cloud

TDMQ for MQTT

Client Event

Introduction

Obtain Client Events

Best Practices

Scenario 1: Client Connection Failure Troubleshooting

Troubleshooting Steps

Scenario 2 Client Takeover

Typical Manifestations

Troubleshooting Steps

Solution

Scenario 3: Troubleshooting Undelivered Messages

Common Disconnection Reasons Reference Table

ヘルプとサポート

Disconnection Reason	Semantics	Recommended Solution
normal	The server received the DISCONNECT message and disconnected normally.	Normal event. Confirm whether the client-initiated disconnection is expected by business logic (for example, the client actively exits upon task completion).
takeovered	The client was disconnected by a device with the same client ID.	Client ID conflict. Check the client ID generation policy to ensure each online device has a unique client ID. (If it is an occasional single occurrence, it may be an automatic recovery after network fluctuation, and no action is required.)
kicked	The client was forced to log out by management.	Administrative action. Please check the management console or API call logs of the MQTT service to confirm which administrator or automated policy performed the force-logout action and why.
keepalive_timeout	The MQTT Broker node did not receive an interactive message from the client within 1.5 times the keep-alive period.	Network or client issue. 1. Check whether the device network connection is stable. 2. Check whether the device CPU/memory load is too high, resulting in failure to send heartbeat packets in time. 3. In a weak network environment, you may appropriately increase the keep-alive value.
not_authenticated	Unauthenticated, similar to HTTP status code 401.	Authentication information error. Check whether the username, password, certificate, or Token configured for the client is correct and whether it matches the server-side configuration.
not_authorized	Unauthorized, similar to HTTP status code 403.	Insufficient permissions. The client is authenticated but lacks permission to connect or perform operations (such as publishing/subscribing to specific topics). Check the ACL policy configuration and grant necessary permissions to this client.
tcp_closed	TCP connection closed.	Network layer disconnected. Possible causes include device network interruption, NAT Gateway timeout, or firewall policy blocking.
ping_without_connect	The client sent a PING before sending the CONNECT packet.	Client SDK/firmware Bug. Check and fix the client MQTT protocol implementation code to ensure strict adherence to the connection establishment sequence: CONNECT -> other packets.
authentication_expired	Authentication failed. JWT/SAS tokens have expired.	Credentials expired. The client program should have the capability to refresh Token.
too_many_connection	Exceeding the maximum cluster/node connections.	Server-side capacity issue. 1. Contact Us to upgrade your service specifications or increase the maximum connection limit. 2. Troubleshoot whether client-side exceptions (such as code bugs) are causing the creation of a large number of invalid connections.
go_away	MQTT Broker node restart, graceful shutdown.	Usually caused by server-side upgrades or maintenance. The client should implement an automatic reconnection mechanism to automatically reconnect after the server recovers.
client_id_too_long	Client ID exceeds the maximum limit.	Client ID exceeds the maximum length. Check the ID length (the MQTT protocol's inherent limit of 23 characters) and modify the client ID generation logic.
client_id_required	Persistent session connection lacks the required client ID field.	Client protocol error. When CleanSession=false, the client ID cannot be empty. Please fix the client logic: either provide an ID or set CleanSession to true.
client_id_invalid	Client ID contains invalid characters. For details, see Spec 3.1.3.1.	Client ID is non-compliant. Client ID can only contain [0-9a-zA-Z] characters. Please modify the client ID generation logic to remove or replace invalid characters.
bad_will_message	Illegal will message.	Will message configuration error. Check the will message (Will Message) set by the client, ensure its topic (Topic) and payload (Payload) formats are correct, and verify that the client has permission to publish messages to the specified will topic.
server_internal_error	Internal server error.	Server issue. Please contact us and provide relevant information (such as timestamp, instance ID, and client ID) to troubleshoot server issues.