{
  "id": "grpc/stream-idle-timeout-reset",
  "signature": "INTERNAL: grpc: stream 45 closed with error: stream idled out",
  "signature_zh": "内部错误：gRPC 流 45 因空闲超时关闭",
  "regex": "INTERNAL: grpc: stream \\d+ closed with error: stream idled out",
  "domain": "grpc",
  "category": "runtime_error",
  "subcategory": null,
  "root_cause": "gRPC server closed an idle stream due to per-stream idle timeout configuration, often caused by client not sending data within the timeout window.",
  "root_cause_type": "generic",
  "root_cause_zh": "gRPC 服务器因每流空闲超时配置关闭了空闲流，通常由客户端在超时窗口内未发送数据引起。",
  "versions": [
    {
      "version": "gRPC v1.50.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "gRPC v1.62.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "gRPC v1.64.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Keepalive pings prevent connection-level idle, but per-stream idle timeouts are separate and not affected by keepalive pings.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This controls minimum allowed ping interval, not stream idle timeout; it doesn't prevent stream closure due to inactivity.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Removing keepalive can cause connection drops, but stream idle timeout is a separate server-side policy that still applies.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Increase the server-side stream idle timeout using gRPC server option: `server = grpc.server(futures.ThreadPoolExecutor(max_workers=10), options=[('grpc.max_connection_idle_ms', 60000)])` in Python, or set `GRPC_ARG_MAX_CONNECTION_IDLE_MS` in C++. This prevents idle streams from being closed too aggressively.",
      "success_rate": 0.85,
      "how": "Increase the server-side stream idle timeout using gRPC server option: `server = grpc.server(futures.ThreadPoolExecutor(max_workers=10), options=[('grpc.max_connection_idle_ms', 60000)])` in Python, or set `GRPC_ARG_MAX_CONNECTION_IDLE_MS` in C++. This prevents idle streams from being closed too aggressively.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Ensure the client sends periodic data or uses bidirectional streaming with a heartbeat message every 10-15 seconds to keep the stream active.",
      "success_rate": 0.8,
      "how": "Ensure the client sends periodic data or uses bidirectional streaming with a heartbeat message every 10-15 seconds to keep the stream active.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Reduce the server's `max_connection_age_ms` and `max_connection_age_grace_ms` to force connection rebalancing, which can reset idle counters.",
      "success_rate": 0.75,
      "how": "Reduce the server's `max_connection_age_ms` and `max_connection_age_grace_ms` to force connection rebalancing, which can reset idle counters.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "增加服务器端流空闲超时时间：在 Python 中设置 `grpc.max_connection_idle_ms` 为 60000 毫秒，或 C++ 中设置 `GRPC_ARG_MAX_CONNECTION_IDLE_MS`，避免空闲流过早关闭。",
    "客户端定期发送数据或心跳消息（每 10-15 秒），保持流活跃。",
    "降低服务器 `max_connection_age_ms` 和 `max_connection_age_grace_ms`，强制连接重新平衡，重置空闲计数器。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://grpc.io/docs/guides/keepalive/",
  "official_doc_section": null,
  "error_code": "GRPC_STREAM_IDLE_TIMEOUT",
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2024-03-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}