SeleniumHQ/selenium · error · WebDriverException

Element or locator must be given when calling below method

Error message

Element or locator must be given when calling below method

What it means

RelativeBy.below requires a non-null element_or_locator; a falsy value raises WebDriverException naming the 'below' method.

Source

Thrown at py/selenium/webdriver/support/relative_locator.py:145

    def below(self, element_or_locator: WebElement | dict | None = None) -> "RelativeBy":
        """Add a filter to look for elements below.

        Args:
            element_or_locator: Element to look below

        Returns:
            RelativeBy

        Raises:
            WebDriverException: If `element_or_locator` is None.

        Example:
            >>> highest = driver.find_element(By.ID, "high")
            >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").below(highest))
        """
        if not element_or_locator:
            raise WebDriverException("Element or locator must be given when calling below method")

        self.filters.append({"kind": "below", "args": [element_or_locator]})
        return self

    @overload
    def to_left_of(self, element_or_locator: WebElement | LocatorType) -> "RelativeBy": ...

    @overload
    def to_left_of(self, element_or_locator: None = None) -> "NoReturn": ...

    def to_left_of(self, element_or_locator: WebElement | dict | None = None) -> "RelativeBy":
        """Add a filter to look for elements to the left of.

        Args:
            element_or_locator: Element to look to the left of

        Returns:
            RelativeBy

View on GitHub (pinned to aa36b38e69)

Solutions

Resolve and verify the anchor element/locator before chaining .below().
Guard the value before calling.
Use find_element for anchors so a miss surfaces early.

Example fix

# before
anchor = maybe_find()
elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").below(anchor))

# after
anchor = driver.find_element(By.ID, "anchor")
elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").below(anchor))

Defensive patterns

Strategy: type-guard

Validate before calling

if not element_or_locator:
    raise ValueError("anchor required before .below()")

Type guard

from selenium.webdriver.remote.webelement import WebElement
def is_anchor(v) -> bool:
    return isinstance(v, WebElement) or (isinstance(v, dict) and v)

Prevention

Assert the anchor is non-None before chaining direction methods.
Resolve anchors with find_element, not optional lookups.

When it happens

Trigger: Chaining .below(None) or passing an empty dict / unresolved lookup.

Common situations: Piping a not-found anchor straight into .below().

Related errors

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