{"record":{"id":"1e925f0410bd1637","repo":"SeleniumHQ/selenium","slug":"frame-reference","errorCode":null,"errorMessage":"{frame_reference}","messagePattern":"\\{frame_reference\\}","errorType":"exception","errorClass":"NoSuchFrameException","httpStatus":null,"severity":"error","filePath":"py/selenium/webdriver/remote/switch_to.py","lineNumber":87,"sourceCode":"        \"\"\"Switch focus to the specified frame by index, name, or element.\n\n        Args:\n            frame_reference: The name of the frame to switch to, an integer representing the index,\n                or a WebElement that is an (i)frame to switch to.\n\n        Example:\n                driver.switch_to.frame(\"frame_name\")\n                driver.switch_to.frame(1)\n                driver.switch_to.frame(driver.find_elements(By.TAG_NAME, \"iframe\")[0])\n        \"\"\"\n        if isinstance(frame_reference, str):\n            try:\n                frame_reference = self._driver.find_element(By.ID, frame_reference)\n            except NoSuchElementException:\n                try:\n                    frame_reference = self._driver.find_element(By.NAME, frame_reference)\n                except NoSuchElementException as exc:\n                    raise NoSuchFrameException(frame_reference) from exc\n\n        self._driver.execute(Command.SWITCH_TO_FRAME, {\"id\": frame_reference})\n\n    def new_window(self, type_hint: str | None = None) -> None:\n        \"\"\"Switches to a new top-level browsing context.\n\n        The type hint can be one of \"tab\" or \"window\". If not specified the\n        browser will automatically select it.\n\n        Example:\n                driver.switch_to.new_window(\"tab\")\n        \"\"\"\n        value = self._driver.execute(Command.NEW_WINDOW, {\"type\": type_hint})[\"value\"]\n        self._w3c_window(value[\"handle\"])\n\n    def parent_frame(self) -> None:\n        \"\"\"Switch focus to the parent browsing context.\n","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/SeleniumHQ/selenium/blob/aa36b38e696a0909e973bdf5e2f9031ffe842c4b/py/selenium/webdriver/remote/switch_to.py#L69-L105","documentation":"Raised by `switch_to.frame` when the frame_reference is a string that matches no element by `id` and no element by `name` (both lookups raised NoSuchElementException). For strings the driver first tries id then name; only if both miss does it raise NoSuchFrameException, passing the original reference as the message. Integer indices and WebElements bypass this and are sent straight to the W3C frame command (which may raise its own NoSuchFrameException server-side).","triggerScenarios":"switch_to.frame('wrong_name'), a stale or mistyped id/name, an iframe whose id/name changed after a page update, or switching before the iframe is present in the DOM.","commonSituations":"Dynamic SPA that renders iframes asynchronously; switching frames right after a navigation before the iframe exists; typos in the frame name; id vs name confusion.","solutions":["Wait for the iframe element to be present, then pass the WebElement: driver.switch_to.frame(driver.find_element(By.CSS_SELECTOR, 'iframe')).","Verify the id/name actually exists before switching.","Use an explicit index or a located element rather than guessing a string."],"exampleFix":"# before\ndriver.switch_to.frame('menu')  # 'menu' is neither id nor name\n\n# after\nfrom selenium.webdriver.support.ui import WebDriverWait\nfrom selenium.webdriver.common.by import By\niframe = WebDriverWait(driver, 10).until(\n    EC.presence_of_element_located((By.CSS_SELECTOR, 'iframe[src*=menu]')))\ndriver.switch_to.frame(iframe)","handlingStrategy":"try-catch","validationCode":"els = driver.find_elements(By.CSS_SELECTOR, f'iframe#{name}, iframe[name=\"{name}\"]')\nif not els:\n    raise NoSuchFrameException(f'no iframe with id/name {name!r}')","typeGuard":null,"tryCatchPattern":"from selenium.common.exceptions import NoSuchFrameException\ntry:\n    driver.switch_to.frame(name)\nexcept NoSuchFrameException:\n    # iframe not ready/absent; wait + retry, or fall back to a located element","preventionTips":["Always locate the iframe as a WebElement and wait for it before switching.","Don't assume string names resolve; prefer explicit element locators."],"tags":["frames","locator","synchronization","switch-to"],"backgroundTag":null,"analyzedSha":"aa36b38e696a0909e973bdf5e2f9031ffe842c4b","analyzedAt":"2026-08-14T02:32:32.244Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}