{"record":{"id":"03ee06c609de4ac1","repo":"SeleniumHQ/selenium","slug":"element-or-locator-must-be-given-when-calling-near","errorCode":null,"errorMessage":"Element or locator must be given when calling near method","messagePattern":"Element or locator must be given when calling near method","errorType":"exception","errorClass":"WebDriverException","httpStatus":null,"severity":"error","filePath":"py/selenium/webdriver/support/relative_locator.py","lineNumber":303,"sourceCode":"        \"\"\"Add a filter to look for elements near.\n\n        Args:\n            element_or_locator: Element to look near by the element or within a distance\n            distance: Distance in pixel\n\n        Returns:\n            RelativeBy\n\n        Raises:\n            WebDriverException: If `element_or_locator` is None\n            WebDriverException: If `distance` is less than or equal to 0.\n\n        Example:\n            >>> near = driver.find_element(By.ID, \"near\")\n            >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, \"p\").near(near, 50))\n        \"\"\"\n        if not element_or_locator:\n            raise WebDriverException(\"Element or locator must be given when calling near method\")\n        if distance <= 0:\n            raise WebDriverException(\"Distance must be positive\")\n\n        self.filters.append({\"kind\": \"near\", \"args\": [element_or_locator, distance]})\n        return self\n\n    def to_dict(self) -> dict:\n        \"\"\"Create a dict to be passed to the driver for element searching.\"\"\"\n        return {\n            \"relative\": {\n                \"root\": self.root,\n                \"filters\": self.filters,\n            }\n        }\n","sourceCodeStart":285,"sourceCodeEnd":318,"githubUrl":"https://github.com/SeleniumHQ/selenium/blob/aa36b38e696a0909e973bdf5e2f9031ffe842c4b/py/selenium/webdriver/support/relative_locator.py#L285-L318","documentation":"`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.","triggerScenarios":"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.","commonSituations":"Passing an uninitialised locator variable; refactoring and dropping the anchor argument; dynamically computing an anchor that is None on some pages.","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"],"exampleFix":"// before\nloc = locate_with(By.CSS_SELECTOR, \"p\").near()\n\n// after\nnear = driver.find_element(By.ID, \"near\")\nloc = locate_with(By.CSS_SELECTOR, \"p\").near(near, 50)","handlingStrategy":"validation","validationCode":"near = driver.find_element(By.ID, \"near\")\nif near is None:\n    raise ValueError(\"near anchor not found\")\nloc = locate_with(By.CSS_SELECTOR, \"p\").near(near, 50)","typeGuard":"from selenium.webdriver.remote.webelement import WebElement\n\ndef is_valid_anchor(v) -> bool:\n    return isinstance(v, WebElement) or (isinstance(v, dict) and len(v) > 0)","tryCatchPattern":null,"preventionTips":["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"],"tags":["relative-locator","validation","selenium-python"],"backgroundTag":null,"analyzedSha":"aa36b38e696a0909e973bdf5e2f9031ffe842c4b","analyzedAt":"2026-08-14T02:32:32.244Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}