Client Event

Modo Foco

Tamanho da Fonte

Última atualização: 2026-04-01 16:37:51

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 identify and analyze problems to quickly resolve service issues, thereby ensuring system stability.
Obtaining Client Events
It is recommended that you obtain client events using one of the following two methods. For detailed field definitions and full content of client events, see Querying Client Events.
Method 1: Query in the Console
1. Log in to the MQTT Console.
2. In the left sidebar, choose Resource > Cluster, select a region, and click the ID of the target cluster to go to 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 details, refer to the Event Topics section in the Querying Client Events documentation.
Best Practices
Scenario 1: Client Connection Failure Troubleshooting
Device logs indicate connection failure or disconnection, or the client list status shows "offline" in the console.
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 reason field of the client_disconnected event. For definitions of specific 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 refers to the behavior where, when a client initiates a connection with a client ID that is already in use, the broker forcibly disconnects the existing session and establishes a new one. The MQTT protocol requires that only one connection can exist for the same client ID at any given time.
Troubleshooting Steps
View the event timeline in the console.
Check whether there is a frequent alternation betweenclient_connected and client_disconnected.
Check the reason field of the client_disconnected event. If the reason is takeovered (one of the most typical causes of client connection jitter), it indicates that the current client was taken over by another device using the same client ID.
Solutions
Ensure that each device's Client ID is globally unique.
Check whether any old test scripts are still running.
Note:
When troubleshooting of takeover issues is performed, not all instances of reason: takeovered 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 Trace.
Determine online status using events: Obtain the message delivery timestamp via Message Trace and check if there is a client_disconnected event at that time to determine whether the device experienced a brief disconnection.
Determine subscription behavior using events: Check whether there is a session_subscribed event to determine whether the device has successfully subscribed to the target topic.
For detailed troubleshooting steps of consumption process issues such as "message loss" and "ACK unacknowledged", please refer to Message Trace.
Common Disconnection Reasons Reference Table
Disconnection Reason
Semantics
Recommended Solution
normal
The server received the DISCONNECT message and disconnected normally.
Normal event. The client initiated the disconnection. Verify whether this matches 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 occurs occasionally, it may be an automatic recovery after network fluctuation, and no action is required.)
kicked
The client was forced to log out by an administrator.
Administration action. Check the MQTT service management console or API call logs to identify which administrator or automated policy performed the force-logout action and the reason for it.
keepalive_timeout
The MQTT Broker did not receive any interaction packets from the client within 1.5 times the keep-alive interval.
Network or client issue.
1.  Check whether the device network connection is stable.
2.  Check whether the device's CPU or memory load is too high, resulting in failure to send heartbeat packets in time.
3.  Under poor network conditions, you can increase the keep-alive value as needed.
not_authenticated
Unauthenticated, similar to HTTP status code 401.
Authentication information error. Check whether the username, password, certificate, and token configured for the client are correct and whether they match the server-side configuration.
not_authorized
Unauthorized, similar to HTTP status code 403.
Insufficient permissions. The client is authenticated but not authorized to connect or perform operations (such as publishing or subscribing to specific topics). Check the ACL policy configuration and grant the 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 or firmware bugs. Check and fix the client's MQTT protocol implementation code to ensure it strictly adheres to the connection sequence: CONNECT > other packets.
authentication_expired
Authentication failed. JWT, SAS, or other tokens have expired.
Credentials expired. Ensure the client program can refresh the token.
too_many_connection
Maximum connections for the cluster or node exceeded.
Server capacity issue.
1. Contact Us to upgrade your service specifications or increase the maximum connection limit.
2. Check whether any client exceptions (such as code bugs) are causing a large number of invalid connections.
go_away
The MQTT Broker node is restarting (graceful shutdown).
Typically caused by server upgrades or maintenance. The client should implement an automatic reconnection mechanism to reconnect once the server is available.
client_id_too_long
Client ID exceeds the maximum limit.
The client ID exceeds the length limit. Check the ID length (MQTT limit: 23 characters) and modify the client ID generation logic.
client_id_required
The required client ID field is missing for a persistent session connection.
Client protocol error. When CleanSession is set to false, the client ID cannot be empty. Please fix the client logic by either providing an ID or setting CleanSession to true.
client_id_invalid
The client ID contains invalid characters. For details, see Spec 3.1.3.1.
Invalid client ID. The client ID can only contain digits 0–9, lowercase letters a–z, and uppercase letters A–Z. Please modify the client ID generation logic to remove or replace invalid characters.
bad_will_message
Invalid will message.
Will message configuration error. Check the will message set for the client to ensure that the topic and payload formats are correct, and that the client has permission to publish 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.

Ajuda e Suporte

Esta página foi útil?

Você também pode entrar em contato com a Equipe de vendas ou Enviar um tíquete em caso de ajuda.

comentários

tencent cloud

TDMQ for MQTT

Client Event

Introduction

Obtaining Client Events

Best Practices

Scenario 1: Client Connection Failure Troubleshooting

Troubleshooting Steps

Scenario 2: Client Takeover

Typical Manifestations

Troubleshooting Steps

Solutions

Scenario 3: Troubleshooting Undelivered Messages

Common Disconnection Reasons Reference Table

Ajuda e Suporte

Disconnection Reason	Semantics	Recommended Solution
normal	The server received the DISCONNECT message and disconnected normally.	Normal event. The client initiated the disconnection. Verify whether this matches 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 occurs occasionally, it may be an automatic recovery after network fluctuation, and no action is required.)
kicked	The client was forced to log out by an administrator.	Administration action. Check the MQTT service management console or API call logs to identify which administrator or automated policy performed the force-logout action and the reason for it.
keepalive_timeout	The MQTT Broker did not receive any interaction packets from the client within 1.5 times the keep-alive interval.	Network or client issue. 1. Check whether the device network connection is stable. 2. Check whether the device's CPU or memory load is too high, resulting in failure to send heartbeat packets in time. 3. Under poor network conditions, you can increase the keep-alive value as needed.
not_authenticated	Unauthenticated, similar to HTTP status code 401.	Authentication information error. Check whether the username, password, certificate, and token configured for the client are correct and whether they match the server-side configuration.
not_authorized	Unauthorized, similar to HTTP status code 403.	Insufficient permissions. The client is authenticated but not authorized to connect or perform operations (such as publishing or subscribing to specific topics). Check the ACL policy configuration and grant the 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 or firmware bugs. Check and fix the client's MQTT protocol implementation code to ensure it strictly adheres to the connection sequence: CONNECT > other packets.
authentication_expired	Authentication failed. JWT, SAS, or other tokens have expired.	Credentials expired. Ensure the client program can refresh the token.
too_many_connection	Maximum connections for the cluster or node exceeded.	Server capacity issue. 1. Contact Us to upgrade your service specifications or increase the maximum connection limit. 2. Check whether any client exceptions (such as code bugs) are causing a large number of invalid connections.
go_away	The MQTT Broker node is restarting (graceful shutdown).	Typically caused by server upgrades or maintenance. The client should implement an automatic reconnection mechanism to reconnect once the server is available.
client_id_too_long	Client ID exceeds the maximum limit.	The client ID exceeds the length limit. Check the ID length (MQTT limit: 23 characters) and modify the client ID generation logic.
client_id_required	The required client ID field is missing for a persistent session connection.	Client protocol error. When CleanSession is set to false, the client ID cannot be empty. Please fix the client logic by either providing an ID or setting CleanSession to true.
client_id_invalid	The client ID contains invalid characters. For details, see Spec 3.1.3.1.	Invalid client ID. The client ID can only contain digits 0–9, lowercase letters a–z, and uppercase letters A–Z. Please modify the client ID generation logic to remove or replace invalid characters.
bad_will_message	Invalid will message.	Will message configuration error. Check the will message set for the client to ensure that the topic and payload formats are correct, and that the client has permission to publish 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.