{
  "id": "communication/mqtt-publish-too-large",
  "signature": "MQTT CONNACK with 0x03 (Connection Refused: Server unavailable) due to publish packet too large",
  "signature_zh": "MQTT CONNACK 返回 0x03（连接被拒绝：服务器不可用），原因是发布数据包过大",
  "regex": "CONNACK.*0x03|Connection Refused.*Server unavailable|publish packet too large",
  "domain": "communication",
  "category": "protocol_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "MQTT 代理拒绝了有效载荷超过 CONNACK 中指定的“最大数据包大小”或代理默认限制（通常为 256 KB）的 PUBLISH 数据包。",
  "versions": [
    {
      "version": "Mosquitto 2.0.18",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "EMQX 5.6",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "HiveMQ 4.27",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS IoT Core MQTT 2024-03",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increase the broker's memory limit",
      "why_fails": "The error is about packet size limits, not memory. More memory doesn't raise the maximum allowed packet size.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disable QoS 2 on the publisher",
      "why_fails": "QoS level doesn't affect the maximum packet size; even QoS 0 messages are subject to the same limit.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a different MQTT client library",
      "why_fails": "The limit is enforced by the broker, not the client. A different library won't bypass the broker's restriction.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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.",
      "success_rate": 0.85,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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).",
      "success_rate": 0.8,
      "how": "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).",
      "condition": "",
      "sources": []
    },
    {
      "action": "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.",
      "success_rate": 0.78,
      "how": "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.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "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.",
    "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).",
    "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."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901086",
  "official_doc_section": null,
  "error_code": "0x03",
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2024-01-22",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}