{
  "id": "pytorch/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 control flow or dynamic shapes.",
  "signature_zh": "RuntimeError: torch.compile: 函数 'forward' 因图断裂而失败，回退到 eager 模式。请考虑重写函数以避免控制流或动态形状。",
  "regex": "torch\\.compile.*failed with a graph break",
  "domain": "pytorch",
  "category": "module_error",
  "subcategory": null,
  "root_cause": "The compiled function contains unsupported Python control flow (e.g., if statements, loops with dynamic bounds) or dynamic tensor shapes that prevent the TorchDynamo compiler from capturing a single static computation graph.",
  "root_cause_type": "generic",
  "root_cause_zh": "编译的函数包含不受支持的 Python 控制流（例如，if 语句、动态边界的循环）或动态张量形状，导致 TorchDynamo 编译器无法捕获单个静态计算图。",
  "versions": [
    {
      "version": "PyTorch 2.1.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PyTorch 2.2.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PyTorch 2.3.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.10",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.11",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Disable torch.compile entirely and use eager mode",
      "why_fails": "This removes performance benefits; the model still runs but slower. It does not solve the graph break issue for production deployment.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "Set torch._dynamo.config.optimize_ddp = False",
      "why_fails": "This flag only affects DDP integration, not the core graph break problem caused by control flow or dynamic shapes.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use torch.compile with mode='reduce-overhead' instead of default",
      "why_fails": "Different modes may change compilation behavior but do not eliminate graph breaks from unsupported Python constructs.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Refactor the forward method to use torch.where, torch.masked_select, or precomputed masks instead of if-else branches. Example: if condition: x = x + 1 becomes x = x + condition.float()",
      "success_rate": 0.85,
      "how": "Refactor the forward method to use torch.where, torch.masked_select, or precomputed masks instead of if-else branches. Example: if condition: x = x + 1 becomes x = x + condition.float()",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use torch._dynamo.config.log_level = logging.INFO and torch._dynamo.config.verbose = True to print detailed graph break reasons, then restructure the code accordingly. Example: import logging; logging.basicConfig(level=logging.INFO)",
      "success_rate": 0.9,
      "how": "Use torch._dynamo.config.log_level = logging.INFO and torch._dynamo.config.verbose = True to print detailed graph break reasons, then restructure the code accordingly. Example: import logging; logging.basicConfig(level=logging.INFO)",
      "condition": "",
      "sources": []
    },
    {
      "action": "Mark the problematic function with @torch.compile(disable=True) to fall back to eager mode for that specific function while keeping compilation for the rest of the model.",
      "success_rate": 0.75,
      "how": "Mark the problematic function with @torch.compile(disable=True) to fall back to eager mode for that specific function while keeping compilation for the rest of the model.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Refactor the forward method to use torch.where, torch.masked_select, or precomputed masks instead of if-else branches. Example: if condition: x = x + 1 becomes x = x + condition.float()",
    "Use torch._dynamo.config.log_level = logging.INFO and torch._dynamo.config.verbose = True to print detailed graph break reasons, then restructure the code accordingly. Example: import logging; logging.basicConfig(level=logging.INFO)",
    "Mark the problematic function with @torch.compile(disable=True) to fall back to eager mode for that specific function while keeping compilation for the rest of the model."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://pytorch.org/docs/stable/torch.compiler.html#debugging-graph-breaks",
  "official_doc_section": null,
  "error_code": "TORCH_COMPILE_GRAPH_BREAK",
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-10-01",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}