# MQTT publish failed: no subscribers matched topic filter

- **ID:** `communication/mqtt-publish-failed-no-subscribers`
- **Domain:** communication
- **Category:** runtime_error
- **Verification:** ai_generated
- **Fix Rate:** 75%

## Root Cause

The MQTT broker discards the published message because no active subscribers are subscribed to the topic or any wildcard matching it.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Mosquitto 2.0.15 | active | — | — |
| Paho MQTT 1.6.1 | active | — | — |
| EMQX 5.0.0 | active | — | — |

## Workarounds

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.** (80% success)
   ```
   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.** (75% success)
   ```
   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.** (85% success)
   ```
   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.
   ```

## Dead Ends

- **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% fail)
- **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% fail)
- **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% fail)