# MQTT CONNACK with 0x03 (Connection Refused: Server unavailable) due to publish packet too large

- **ID:** `communication/mqtt-publish-too-large`
- **Domain:** communication
- **Category:** protocol_error
- **Error Code:** `0x03`
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

MQTT broker rejects a PUBLISH packet whose payload exceeds the `Maximum Packet Size` specified in the CONNACK or broker default limit, typically 256 KB for many brokers.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Mosquitto 2.0.18 | active | — | — |
| EMQX 5.6 | active | — | — |
| HiveMQ 4.27 | active | — | — |
| AWS IoT Core MQTT 2024-03 | active | — | — |

## Workarounds

1. **Configure the broker to increase the maximum packet size. For Mosquitto, set `max_packet_size` in mosquitto.conf. For EMQX, set `mqtt.max_packet_size` in emqx.conf.** (85% success)
   ```
   Configure the broker to increase the maximum packet size. For Mosquitto, set `max_packet_size` in mosquitto.conf. For EMQX, set `mqtt.max_packet_size` in emqx.conf.
   ```
2. **Split large payloads into multiple smaller PUBLISH messages on the client side, and reassemble on the subscriber using a topic-specific convention (e.g., chunked/ prefix).** (80% success)
   ```
   Split large payloads into multiple smaller PUBLISH messages on the client side, and reassemble on the subscriber using a topic-specific convention (e.g., chunked/ prefix).
   ```
3. **Enable MQTT v5.0 and negotiate the maximum packet size during CONNECT by setting the `Maximum Packet Size` property to a value acceptable to both client and broker.** (78% success)
   ```
   Enable MQTT v5.0 and negotiate the maximum packet size during CONNECT by setting the `Maximum Packet Size` property to a value acceptable to both client and broker.
   ```

## Dead Ends

- **Increase the broker's memory limit** — The error is about packet size limits, not memory. More memory doesn't raise the maximum allowed packet size. (90% fail)
- **Disable QoS 2 on the publisher** — QoS level doesn't affect the maximum packet size; even QoS 0 messages are subject to the same limit. (85% fail)
- **Use a different MQTT client library** — The limit is enforced by the broker, not the client. A different library won't bypass the broker's restriction. (95% fail)