{
  "id": "communication/mqtt-publish-identifier-already-in-use",
  "signature": "MQTT protocol violation: Identifier already in use (CONNACK code 2)",
  "signature_zh": "MQTT协议违规：标识符已在使用（CONNACK代码2）",
  "regex": "Identifier already in use|CONNACK.*code 2|Client Identifier not unique",
  "domain": "communication",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "An MQTT client attempts to connect with a Client Identifier that is already in use by another active connection to the same broker, violating the uniqueness requirement of MQTT v3.1.1 section 3.1.3 and MQTT v5.0 section 3.1.3.",
  "root_cause_type": "generic",
  "root_cause_zh": "MQTT客户端尝试使用已被同一代理上另一个活动连接使用的客户端标识符进行连接，违反了MQTT v3.1.1第3.1.3节和MQTT v5.0第3.1.3节中的唯一性要求。",
  "versions": [
    {
      "version": "Mosquitto 2.0.18",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "EMQX 5.3.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "HiveMQ 4.28.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "VerneMQ 1.13.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS IoT Core MQTT endpoint",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Disable the 'allow_multiple_connections' flag in the broker to force single connections",
      "why_fails": "This flag controls whether multiple connections with the same ID are allowed; disabling it only enforces the error, it doesn't fix the client's duplicate ID.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Restart the broker to clear all active connections",
      "why_fails": "Restarting is a temporary fix that clears all sessions; the duplicate ID problem reappears when the same client reconnects without changing its ID.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a static Client Identifier that is hardcoded in the firmware",
      "why_fails": "Static IDs guarantee collisions if multiple devices run the same firmware; they also make session state management impossible.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Generate a unique Client Identifier per connection using a combination of device MAC address and Unix timestamp: in Python, use 'client_id = f\"device-{mac}-{int(time.time())}\"'.",
      "success_rate": 0.95,
      "how": "Generate a unique Client Identifier per connection using a combination of device MAC address and Unix timestamp: in Python, use 'client_id = f\"device-{mac}-{int(time.time())}\"'.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Enable 'clean_session' (MQTT v3.1.1) or 'session_expiry_interval=0' (MQTT v5) on the client to force the broker to discard previous session state when a duplicate ID is detected.",
      "success_rate": 0.85,
      "how": "Enable 'clean_session' (MQTT v3.1.1) or 'session_expiry_interval=0' (MQTT v5) on the client to force the broker to discard previous session state when a duplicate ID is detected.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Configure the broker to allow multiple connections with the same Client ID (e.g., Mosquitto: 'allow_duplicate_client_ids true'), but only if session isolation is not required.",
      "success_rate": 0.7,
      "how": "Configure the broker to allow multiple connections with the same Client ID (e.g., Mosquitto: 'allow_duplicate_client_ids true'), but only if session isolation is not required.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Generate a unique Client Identifier per connection using a combination of device MAC address and Unix timestamp: in Python, use 'client_id = f\"device-{mac}-{int(time.time())}\"'.",
    "Enable 'clean_session' (MQTT v3.1.1) or 'session_expiry_interval=0' (MQTT v5) on the client to force the broker to discard previous session state when a duplicate ID is detected.",
    "Configure the broker to allow multiple connections with the same Client ID (e.g., Mosquitto: 'allow_duplicate_client_ids true'), but only if session isolation is not required."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718030",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2023-09-28",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}