{
  "id": "embedded/lwip-memory-pool-exhaustion",
  "signature": "lwIP: mem_malloc failed: PBUF_POOL exhausted",
  "signature_zh": "lwIP：mem_malloc 失败：PBUF_POOL 耗尽",
  "regex": "lwIP: mem_malloc failed: PBUF_POOL exhausted",
  "domain": "embedded",
  "category": "resource_error",
  "subcategory": null,
  "root_cause": "The lwIP TCP/IP stack's PBUF pool is depleted due to excessive packet allocation without timely freeing, often from a burst of incoming data or a memory leak in the application.",
  "root_cause_type": "generic",
  "root_cause_zh": "lwIP TCP/IP 协议栈的 PBUF 池因数据包分配过多且未及时释放而耗尽，通常由突发输入数据或应用程序内存泄漏引起。",
  "versions": [
    {
      "version": "lwIP 2.1.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "lwIP 2.0.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "FreeRTOS+TCP 2.0.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Increasing PBUF_POOL_SIZE in lwipopts.h without analyzing actual usage often masks the underlying issue, causing out-of-memory elsewhere.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Setting PBUF_POOL_SIZE to a very large value may exhaust heap memory, leading to system crashes or HardFaults.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Adding more debug prints in the packet processing path can increase memory pressure and worsen the exhaustion.",
      "fail_rate": 0.3,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Increase PBUF_POOL_SIZE and PBUF_POOL_BUFSIZE in lwipopts.h. For example:\n#define PBUF_POOL_SIZE 20\n#define PBUF_POOL_BUFSIZE 1518",
      "success_rate": 0.7,
      "how": "Increase PBUF_POOL_SIZE and PBUF_POOL_BUFSIZE in lwipopts.h. For example:\n#define PBUF_POOL_SIZE 20\n#define PBUF_POOL_BUFSIZE 1518",
      "condition": "",
      "sources": []
    },
    {
      "action": "Implement a packet rate limiter in the network receive callback to drop excess packets. Example:\nif (p->tot_len > MAX_PACKET_SIZE) { pbuf_free(p); return ERR_MEM; }",
      "success_rate": 0.8,
      "how": "Implement a packet rate limiter in the network receive callback to drop excess packets. Example:\nif (p->tot_len > MAX_PACKET_SIZE) { pbuf_free(p); return ERR_MEM; }",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use memory profiling with lwIP's stats API (lwip_stats.mem.used) to identify the real bottleneck and adjust pool sizes accordingly.",
      "success_rate": 0.9,
      "how": "Use memory profiling with lwIP's stats API (lwip_stats.mem.used) to identify the real bottleneck and adjust pool sizes accordingly.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Increase PBUF_POOL_SIZE and PBUF_POOL_BUFSIZE in lwipopts.h. For example:\n#define PBUF_POOL_SIZE 20\n#define PBUF_POOL_BUFSIZE 1518",
    "Implement a packet rate limiter in the network receive callback to drop excess packets. Example:\nif (p->tot_len > MAX_PACKET_SIZE) { pbuf_free(p); return ERR_MEM; }",
    "Use memory profiling with lwIP's stats API (lwip_stats.mem.used) to identify the real bottleneck and adjust pool sizes accordingly."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://www.nongnu.org/lwip/2_1_x/group__pbuf.html",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.78,
  "resolvable": "true",
  "first_seen": "2023-06-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}