SeleniumHQ/selenium · error · NoSuchFrameException

{frame_reference}

Error message

{frame_reference}

What it means

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).

Source

Thrown at py/selenium/webdriver/remote/switch_to.py:87

        """Switch focus to the specified frame by index, name, or element.

        Args:
            frame_reference: The name of the frame to switch to, an integer representing the index,
                or a WebElement that is an (i)frame to switch to.

        Example:
                driver.switch_to.frame("frame_name")
                driver.switch_to.frame(1)
                driver.switch_to.frame(driver.find_elements(By.TAG_NAME, "iframe")[0])
        """
        if isinstance(frame_reference, str):
            try:
                frame_reference = self._driver.find_element(By.ID, frame_reference)
            except NoSuchElementException:
                try:
                    frame_reference = self._driver.find_element(By.NAME, frame_reference)
                except NoSuchElementException as exc:
                    raise NoSuchFrameException(frame_reference) from exc

        self._driver.execute(Command.SWITCH_TO_FRAME, {"id": frame_reference})

    def new_window(self, type_hint: str | None = None) -> None:
        """Switches to a new top-level browsing context.

        The type hint can be one of "tab" or "window". If not specified the
        browser will automatically select it.

        Example:
                driver.switch_to.new_window("tab")
        """
        value = self._driver.execute(Command.NEW_WINDOW, {"type": type_hint})["value"]
        self._w3c_window(value["handle"])

    def parent_frame(self) -> None:
        """Switch focus to the parent browsing context.

View on GitHub (pinned to aa36b38e69)

Solutions

1. Wait for the iframe element to be present, then pass the WebElement: driver.switch_to.frame(driver.find_element(By.CSS_SELECTOR, 'iframe')).
2. Verify the id/name actually exists before switching.
3. Use an explicit index or a located element rather than guessing a string.

Example fix

# before
driver.switch_to.frame('menu')  # 'menu' is neither id nor name

# after
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.common.by import By
iframe = WebDriverWait(driver, 10).until(
    EC.presence_of_element_located((By.CSS_SELECTOR, 'iframe[src*=menu]')))
driver.switch_to.frame(iframe)

els = driver.find_elements(By.CSS_SELECTOR, f'iframe#{name}, iframe[name="{name}"]')
if not els:
    raise NoSuchFrameException(f'no iframe with id/name {name!r}')

from selenium.common.exceptions import NoSuchFrameException
try:
    driver.switch_to.frame(name)
except NoSuchFrameException:
    # iframe not ready/absent; wait + retry, or fall back to a located element

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot locate relative element with: {by.root}
• input must be a string
• Invalid locator
• Cannot locate option with value: ${value}
• Cannot locate option with text: ${text}

AI-assisted analysis of SeleniumHQ/selenium@aa36b38e69 (2026-08-14). Data as JSON: /api/errors/1e925f0410bd1637. Report an issue: GitHub.