diff --git a/src/UserGuide/Master/Table/API/Programming-MQTT.md b/src/UserGuide/Master/Table/API/Programming-MQTT.md
index 0a1ba4ecc..91dec2b81 100644
--- a/src/UserGuide/Master/Table/API/Programming-MQTT.md
+++ b/src/UserGuide/Master/Table/API/Programming-MQTT.md
@@ -230,4 +230,16 @@ Then, in your server:
 5. Now IoTDB will use your implementation to parse the MQTT message.
 
 More: the message format can be anything you want. For example, if it is a binary format,
-just use `payload.forEachByte()` or `payload.array` to get bytes content. 
\ No newline at end of file
+just use `payload.forEachByte()` or `payload.array` to get bytes content. 
+
+## 7. Caution
+
+To avoid compatibility issues caused by a default client_id, always explicitly supply a unique, non-empty client_id in every MQTT client.
+Behavior varies when the client_id is missing or empty. Common examples:
+1. Explicitly sending an empty string
+• MQTTX: When client_id="", IoTDB silently discards the message.
+• mosquitto_pub: When client_id="", IoTDB receives the message normally.
+2. Omitting client_id entirely
+• MQTTX: IoTDB accepts the message.
+• mosquitto_pub: IoTDB rejects the connection.
+Therefore, explicitly assigning a unique, non-empty client_id is the simplest way to eliminate these discrepancies and ensure reliable message delivery.
\ No newline at end of file
diff --git a/src/UserGuide/Master/Tree/API/Programming-MQTT.md b/src/UserGuide/Master/Tree/API/Programming-MQTT.md
index fdb32543f..df230ecd6 100644
--- a/src/UserGuide/Master/Tree/API/Programming-MQTT.md
+++ b/src/UserGuide/Master/Tree/API/Programming-MQTT.md
@@ -178,5 +178,15 @@ Then, in your server:
 More: the message format can be anything you want. For example, if it is a binary format, 
 just use `payload.forEachByte()` or `payload.array` to get bytes content. 
 
-
+## 6. Caution
+
+To avoid compatibility issues caused by a default client_id, always explicitly supply a unique, non-empty client_id in every MQTT client.
+Behavior varies when the client_id is missing or empty. Common examples:
+1. Explicitly sending an empty string
+   • MQTTX: When client_id="", IoTDB silently discards the message.
+   • mosquitto_pub: When client_id="", IoTDB receives the message normally.
+2. Omitting client_id entirely
+   • MQTTX: IoTDB accepts the message.
+   • mosquitto_pub: IoTDB rejects the connection.
+   Therefore, explicitly assigning a unique, non-empty client_id is the simplest way to eliminate these discrepancies and ensure reliable message delivery.
 
diff --git a/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md b/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md
index 0a8b08d56..56b0261b1 100644
--- a/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md
+++ b/src/zh/UserGuide/Master/Table/API/Programming-MQTT.md
@@ -232,3 +232,18 @@ public class CustomizedLinePayloadFormatter implements PayloadFormatter {
 
 More: MQTT 协议的消息不限于 line，你还可以用任意二进制。通过如下函数获得：
 `payload.forEachByte()` or `payload.array`。 
+
+## 7. 注意事项
+
+为避免因缺省client_id引发的兼容性问题，强烈建议在所有MQTT客户端中始终显式地提供唯一且非空的 client_id。
+不同客户端在client_id缺失或为空时的表现并不一致，常见示例如下：
+1. 显式传入空字符串
+• MQTTX：client_id=""时，IoTDB会直接丢弃消息；
+• mosquitto_pub：client_id=""时，IoTDB能正常接收消息。
+2. 完全不传client_id
+• MQTTX：消息可被IoTDB正常接收；
+• mosquitto_pub：IoTDB拒绝连接。
+由此可见，显式指定唯一且非空的client_id是消除上述差异、确保消息可靠投递的最简单做法。
+
+
+
diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md b/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md
index c291b1e62..9bcff3885 100644
--- a/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md
+++ b/src/zh/UserGuide/Master/Tree/API/Programming-MQTT.md
@@ -176,3 +176,16 @@ public class CustomizedJsonPayloadFormatter implements PayloadFormatter {
 
 More: MQTT 协议的消息不限于 json，你还可以用任意二进制。通过如下函数获得：
 `payload.forEachByte()` or `payload.array`。 
+
+
+## 6. 注意事项
+
+为避免因缺省client_id引发的兼容性问题，强烈建议在所有MQTT客户端中始终显式地提供唯一且非空的 client_id。
+不同客户端在client_id缺失或为空时的表现并不一致，常见示例如下：
+1. 显式传入空字符串
+   • MQTTX：client_id=""时，IoTDB会直接丢弃消息；
+   • mosquitto_pub：client_id=""时，IoTDB能正常接收消息。
+2. 完全不传client_id
+   • MQTTX：消息可被IoTDB正常接收；
+   • mosquitto_pub：IoTDB拒绝连接。
+   由此可见，显式指定唯一且非空的client_id是消除上述差异、确保消息可靠投递的最简单做法。
\ No newline at end of file