SeleniumHQ/selenium · error · WebDriverException

Element or locator must be given when calling above method

Error message

Element or locator must be given when calling above method

What it means

RelativeBy.above requires a non-null element_or_locator (a WebElement or a locator dict). Passing a falsy value (None, empty dict, 0) raises WebDriverException naming the 'above' method.

Source

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

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

        Args:
            element_or_locator: Element to look above

        Returns:
            RelativeBy

        Raises:
            WebDriverException: If `element_or_locator` is None.

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

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

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

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

    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

View on GitHub (pinned to aa36b38e69)

Solutions

Resolve and verify the anchor element/locator before chaining .above().
Guard the value with a truthiness/None check before calling.
Use find_element (which raises on miss) rather than optional lookups for anchors.

Example fix

# before
anchor = maybe_find()           # may be None
elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(anchor))

# after
anchor = driver.find_element(By.ID, "anchor")  # raises if absent
elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(anchor))

Defensive patterns

Strategy: type-guard

Validate before calling

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

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

Always assert the anchor is non-None before chaining a direction method.
Prefer find_element over optional lookups for anchor elements.

When it happens

Trigger: Chaining .above(None), or passing a variable holding a lookup result that resolved to None (e.g. find_element returned nothing usable).

Common situations: Resolving an anchor element that was not found and piping it straight into .above().

Related errors

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