{
  "id": "embedded/lwip-memp-pbuf-pool-exhausted",
  "signature": "lwIP: memp_malloc failed: PBUF_POOL exhausted",
  "signature_zh": "lwIP：memp_malloc 失败：PBUF_POOL 耗尽",
  "regex": "lwIP: memp_malloc failed: PBUF_POOL exhausted",
  "domain": "embedded",
  "category": "resource_error",
  "subcategory": null,
  "root_cause": "The lwIP pbuf pool (PBUF_POOL) ran out of free buffers due to network traffic spikes, memory leaks in packet processing, or insufficient pool size configuration in lwipopts.h.",
  "root_cause_type": "generic",
  "root_cause_zh": "lwIP pbuf 池（PBUF_POOL）由于网络流量峰值、数据包处理中的内存泄漏或 lwipopts.h 中池大小配置不足而耗尽空闲缓冲区。",
  "versions": [
    {
      "version": "lwIP v2.1.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "FreeRTOS v10.4.6",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "STM32Cube_FW_F7 v1.17.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increase PBUF_POOL_SIZE to a very large value (e.g., 1000)",
      "why_fails": "Large pools consume excessive RAM; memory exhaustion may cause system instability without fixing the leak.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disable TCP window scaling to reduce buffer usage",
      "why_fails": "TCP performance degrades significantly, and the issue may persist if the leak is in UDP or raw packets.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use dynamic pbuf allocation (PBUF_RAM) instead of pool",
      "why_fails": "Dynamic allocation can fragment heap and cause out-of-memory errors, especially in constrained systems.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Monitor pbuf pool usage with a periodic task: call memp_stats() and log free pbuf count; if below threshold, force free old connections via tcp_abort().",
      "success_rate": 0.85,
      "how": "Monitor pbuf pool usage with a periodic task: call memp_stats() and log free pbuf count; if below threshold, force free old connections via tcp_abort().",
      "condition": "",
      "sources": []
    },
    {
      "action": "Increase PBUF_POOL_SIZE and PBUF_POOL_BUFSIZE in lwipopts.h: set PBUF_POOL_SIZE to 50 and PBUF_POOL_BUFSIZE to 1524 to handle maximum Ethernet frames.",
      "success_rate": 0.8,
      "how": "Increase PBUF_POOL_SIZE and PBUF_POOL_BUFSIZE in lwipopts.h: set PBUF_POOL_SIZE to 50 and PBUF_POOL_BUFSIZE to 1524 to handle maximum Ethernet frames.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Implement a pbuf leak detection: wrap pbuf_alloc() and pbuf_free() with counters, and log stack traces when free count drops below 10% of pool size.",
      "success_rate": 0.75,
      "how": "Implement a pbuf leak detection: wrap pbuf_alloc() and pbuf_free() with counters, and log stack traces when free count drops below 10% of pool size.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用周期性任务监控 pbuf 池使用情况：调用 memp_stats() 并记录空闲 pbuf 数量；如果低于阈值，通过 tcp_abort() 强制释放旧连接。",
    "在 lwipopts.h 中增加 PBUF_POOL_SIZE 和 PBUF_POOL_BUFSIZE：设置 PBUF_POOL_SIZE 为 50，PBUF_POOL_BUFSIZE 为 1524，以处理最大以太网帧。",
    "实现 pbuf 泄漏检测：使用计数器包装 pbuf_alloc() 和 pbuf_free()，当空闲计数低于池大小的 10% 时记录堆栈跟踪。"
  ],
  "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": "MEM_ERR_MEM",
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.81,
  "resolvable": "true",
  "first_seen": "2024-06-01",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}