{
  "id": "pytorch/torch-compile-graph-break-fallback",
  "signature": "RuntimeError: torch.compile: function 'forward' failed with a graph break. Falling back to eager mode. Consider rewriting the function to avoid Python control flow.",
  "signature_zh": "运行时错误：torch.compile：函数 'forward' 因图断裂失败。回退到 eager 模式。考虑重写函数以避免 Python 控制流。",
  "regex": "RuntimeError: torch\\.compile: function 'forward' failed with a graph break\\. Falling back to eager mode\\. Consider rewriting the function to avoid Python control flow\\.",
  "domain": "pytorch",
  "category": "runtime_error",
  "subcategory": null,
  "root_cause": "torch.compile encountered Python control flow (e.g., if statements, loops) that cannot be captured in a single computation graph, causing a graph break and fallback to eager mode.",
  "root_cause_type": "generic",
  "root_cause_zh": "torch.compile 遇到了无法在单个计算图中捕获的 Python 控制流（例如 if 语句、循环），导致图断裂并回退到 eager 模式。",
  "versions": [
    {
      "version": "pytorch>=2.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "torch.compile",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Using torch.jit.script instead of torch.compile",
      "why_fails": "torch.jit.script also has limitations with dynamic control flow and may produce similar errors.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disabling torch.compile entirely and using eager mode",
      "why_fails": "Avoids the error but loses all performance benefits of compilation.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "Adding more decorators like @torch.jit.ignore",
      "why_fails": "May suppress the error but can lead to incorrect graph construction.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Refactor the forward method to replace Python control flow with tensor operations. For example, use `torch.where(condition, x, y)` instead of `if condition: ... else: ...`",
      "success_rate": 0.85,
      "how": "Refactor the forward method to replace Python control flow with tensor operations. For example, use `torch.where(condition, x, y)` instead of `if condition: ... else: ...`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use torch.compiler.disable() decorator on specific submodules that require dynamic control flow: `@torch.compiler.disable`",
      "success_rate": 0.8,
      "how": "Use torch.compiler.disable() decorator on specific submodules that require dynamic control flow: `@torch.compiler.disable`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Enable the 'fullgraph' option in torch.compile to get a detailed trace of where graph breaks occur: `torch.compile(model, fullgraph=True)`",
      "success_rate": 0.75,
      "how": "Enable the 'fullgraph' option in torch.compile to get a detailed trace of where graph breaks occur: `torch.compile(model, fullgraph=True)`",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Refactor the forward method to replace Python control flow with tensor operations. For example, use `torch.where(condition, x, y)` instead of `if condition: ... else: ...`",
    "Use torch.compiler.disable() decorator on specific submodules that require dynamic control flow: `@torch.compiler.disable`",
    "Enable the 'fullgraph' option in torch.compile to get a detailed trace of where graph breaks occur: `torch.compile(model, fullgraph=True)`"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://pytorch.org/docs/stable/compile.html#troubleshooting",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.7,
  "resolvable": "partial",
  "first_seen": "2024-02-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}