SeleniumHQ/selenium · error · WebDriverException

Element or locator must be given when calling near method

Error message

Element or locator must be given when calling near method

What it means

`RelativeBy.near()` adds a relative-locator filter matching elements within a pixel distance of an anchor. It requires a non-empty `element_or_locator`; a falsy value raises WebDriverException before the distance is even considered.

Source

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

        """Add a filter to look for elements near.

        Args:
            element_or_locator: Element to look near by the element or within a distance
            distance: Distance in pixel

        Returns:
            RelativeBy

        Raises:
            WebDriverException: If `element_or_locator` is None
            WebDriverException: If `distance` is less than or equal to 0.

        Example:
            >>> near = driver.find_element(By.ID, "near")
            >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").near(near, 50))
        """
        if not element_or_locator:
            raise WebDriverException("Element or locator must be given when calling near method")
        if distance <= 0:
            raise WebDriverException("Distance must be positive")

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

    def to_dict(self) -> dict:
        """Create a dict to be passed to the driver for element searching."""
        return {
            "relative": {
                "root": self.root,
                "filters": self.filters,
            }
        }

View on GitHub (pinned to aa36b38e69)

Solutions

Pass a valid WebElement or `{By: value}` dict: `locator.near(anchor, distance=50)`
Resolve the anchor first and confirm it is not None before chaining
Rely on the `@overload ... -> NoReturn` None branch for static type-checking

Example fix

// before
loc = locate_with(By.CSS_SELECTOR, "p").near()

// after
near = driver.find_element(By.ID, "near")
loc = locate_with(By.CSS_SELECTOR, "p").near(near, 50)

Defensive patterns

Strategy: validation

Validate before calling

near = driver.find_element(By.ID, "near")
if near is None:
    raise ValueError("near anchor not found")
loc = locate_with(By.CSS_SELECTOR, "p").near(near, 50)

Type guard

from selenium.webdriver.remote.webelement import WebElement

def is_valid_anchor(v) -> bool:
    return isinstance(v, WebElement) or (isinstance(v, dict) and len(v) > 0)

Prevention

Resolve the anchor element before calling near()
Guard optional anchors with an explicit None check
Use the typed overload so a type checker catches the None call

When it happens

Trigger: Calling `locate_with(...).near()` with no argument, `None`, or an empty dict `{}`. Also occurs when the anchor variable is None because the prior `find_element()` did not return a usable element.

Common situations: Passing an uninitialised locator variable; refactoring and dropping the anchor argument; dynamically computing an anchor that is None on some pages.

Related errors

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