{
  "id": "embedded/lwip-pbuf-pool-exhaustion",
  "signature": "lwIP: pbuf_alloc failed: PBUF_POOL exhausted, total=16, free=0, low=0",
  "signature_zh": "lwIP：pbuf_alloc失败：PBUF_POOL耗尽，总计16，空闲0，最低0",
  "regex": "lwIP: pbuf_alloc failed: PBUF_POOL exhausted, total=\\d+, free=\\d+, low=\\d+",
  "domain": "embedded",
  "category": "resource_error",
  "subcategory": null,
  "root_cause": "The lwIP PBUF_POOL memory pool is empty because all buffers are in use, typically due to network traffic spikes, memory leaks from unprocessed packets, or insufficient pool size configuration.",
  "root_cause_type": "generic",
  "root_cause_zh": "lwIP的PBUF_POOL内存池为空，因为所有缓冲区都在使用中，通常由于网络流量峰值、未处理数据包的内存泄漏或池大小配置不足引起。",
  "versions": [
    {
      "version": "lwIP 2.1.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "lwIP 2.2.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "STM32Cube_FW_H7_V1.11.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Larger windows require more buffers; if the pool size isn't increased, exhaustion still occurs under load.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This shifts computation to CPU but doesn't affect buffer allocation; pool exhaustion persists.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "ARP cache management doesn't free PBUF_POOL buffers; those are for packet data, not ARP entries.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Increase PBUF_POOL_SIZE in lwipopts.h (e.g., from 16 to 32 or 64) to handle burst traffic, and reduce PBUF_POOL_BUFSIZE if packet sizes are small.",
      "success_rate": 0.85,
      "how": "Increase PBUF_POOL_SIZE in lwipopts.h (e.g., from 16 to 32 or 64) to handle burst traffic, and reduce PBUF_POOL_BUFSIZE if packet sizes are small.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Add a check in the Ethernet ISR to drop packets if pool is low, preventing system lockup: `if (pbuf_alloc(PBUF_RAW, 0, PBUF_POOL) == NULL) { return ERR_MEM; }`",
      "success_rate": 0.75,
      "how": "Add a check in the Ethernet ISR to drop packets if pool is low, preventing system lockup: `if (pbuf_alloc(PBUF_RAW, 0, PBUF_POOL) == NULL) { return ERR_MEM; }`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Implement a periodic task to free orphaned pbufs by checking `lwip_stats.mem.used` and calling `tcpip_thread()` processing to flush queues.",
      "success_rate": 0.8,
      "how": "Implement a periodic task to free orphaned pbufs by checking `lwip_stats.mem.used` and calling `tcpip_thread()` processing to flush queues.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Increase PBUF_POOL_SIZE in lwipopts.h (e.g., from 16 to 32 or 64) to handle burst traffic, and reduce PBUF_POOL_BUFSIZE if packet sizes are small.",
    "Add a check in the Ethernet ISR to drop packets if pool is low, preventing system lockup: `if (pbuf_alloc(PBUF_RAW, 0, PBUF_POOL) == NULL) { return ERR_MEM; }`",
    "Implement a periodic task to free orphaned pbufs by checking `lwip_stats.mem.used` and calling `tcpip_thread()` processing to flush queues."
  ],
  "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.86,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2024-08-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}