{
  "id": "react/portal-target-not-dom-element",
  "signature": "Error: Target container is not a DOM element. When using createPortal, the second argument must be a valid DOM node.",
  "signature_zh": "错误：目标容器不是DOM元素。使用createPortal时，第二个参数必须是有效的DOM节点。",
  "regex": "Error: Target container is not a DOM element",
  "domain": "react",
  "category": "runtime_error",
  "subcategory": null,
  "root_cause": "The second argument passed to ReactDOM.createPortal is not a valid DOM element (e.g., null, undefined, or a string selector), often because the target element hasn't been rendered yet or the selector is incorrect.",
  "root_cause_type": "generic",
  "root_cause_zh": "传递给ReactDOM.createPortal的第二个参数不是有效的DOM元素（例如null、undefined或字符串选择器），通常是因为目标元素尚未渲染或选择器不正确。",
  "versions": [
    {
      "version": "React 16.0.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "React 17.0.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "React 18.2.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Using document.querySelector('#root') without checking if the element exists",
      "why_fails": "If the DOM element is not yet mounted (e.g., in a component that renders before the target), querySelector returns null.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "Passing a string like '#modal-root' directly to createPortal",
      "why_fails": "createPortal expects a DOM element, not a CSS selector string. It will throw an error because a string is not a node.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Using document.getElementById inside a component that runs before the target is rendered",
      "why_fails": "If the target div is defined in the same component's JSX, it may not exist in the DOM when the portal is created, leading to null.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Ensure the target DOM element exists before calling createPortal by using a ref or checking if the element is available in useEffect.",
      "success_rate": 0.88,
      "how": "Ensure the target DOM element exists before calling createPortal by using a ref or checking if the element is available in useEffect.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Define the target element in the HTML file (e.g., index.html) and ensure it's present before the React app mounts.",
      "success_rate": 0.95,
      "how": "Define the target element in the HTML file (e.g., index.html) and ensure it's present before the React app mounts.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Ensure the target DOM element exists before calling createPortal by using a ref or checking if the element is available in useEffect.",
    "Define the target element in the HTML file (e.g., index.html) and ensure it's present before the React app mounts."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://react.dev/reference/react-dom/createPortal",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.88,
  "resolvable": "true",
  "first_seen": "2023-08-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}