0x03 communication protocol_error ai_generated true

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

ID: communication/mqtt-publish-too-large

Also available as: JSON · Markdown · 中文
80%Fix Rate
86%Confidence
1Evidence
2024-01-22First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Mosquitto 2.0.18 active — — —
EMQX 5.6 active — — —
HiveMQ 4.27 active — — —
AWS IoT Core MQTT 2024-03 active — — —

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.

generic

中文

MQTT 代理拒绝了有效载荷超过 CONNACK 中指定的“最大数据包大小”或代理默认限制（通常为 256 KB）的 PUBLISH 数据包。

Official Documentation

https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901086

Workarounds

  1. 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. 
    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. 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). 
    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. 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. 
    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.

中文步骤

  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.
  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).
  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.

Dead Ends

Common approaches that don't work:

  1. Increase the broker's memory limit 90% fail

    The error is about packet size limits, not memory. More memory doesn't raise the maximum allowed packet size.

  2. Disable QoS 2 on the publisher 85% fail

    QoS level doesn't affect the maximum packet size; even QoS 0 messages are subject to the same limit.

  3. Use a different MQTT client library 95% fail

    The limit is enforced by the broker, not the client. A different library won't bypass the broker's restriction.