# MQTT 发布失败：无订阅者匹配主题过滤器

- **ID:** `communication/mqtt-publish-failed-no-subscribers`
- **领域:** communication
- **类别:** runtime_error
- **验证级别:** ai_generated
- **修复率:** 75%

## 根因

MQTT 代理丢弃发布的消息，因为没有活动订阅者订阅该主题或任何匹配的通配符主题。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Mosquitto 2.0.15 | active | — | — |
| Paho MQTT 1.6.1 | active | — | — |
| EMQX 5.0.0 | active | — | — |

## 解决方案

1. ```
   Ensure at least one subscriber is connected before publishing: In the publisher code, implement a callback to wait for a subscriber presence notification or use a separate health-check topic. For example, in Eclipse Paho Python client, subscribe to '$SYS/broker/clients/connected' to monitor.
   ```
2. ```
   Use MQTT 5.0 subscription identifiers to track active subscribers: Set `SubscriptionIdentifier` in the publish packet and check broker response for 'no matching subscribers' reason code.
   ```
3. ```
   Configure the broker to store undelivered messages with a queue for offline subscribers: In Mosquitto, set `persistence true` and use `max_queued_messages 1000` with a clean session false for the subscriber.
   ```

## 无效尝试

- **Publish with QoS 2 to guarantee delivery even without subscribers** — QoS levels do not create subscribers; the broker still drops the message if no one is subscribed. (85% 失败率)
- **Enable broker's retained messages feature to store the last message** — Retained messages only store the last message per topic; they don't affect delivery of new messages to non-existent subscribers. (70% 失败率)
- **Set the 'clean session' flag to false on the publisher** — The clean session flag applies to client session state, not subscriber existence; it doesn't create subscribers. (90% 失败率)