SeleniumHQ/selenium · warning · WebDriverException

tag_name can not be null

Error message

tag_name can not be null

What it means

The deprecated `locate` factory builds a RelativeBy and requires a non-empty tag_name; passing None or an empty value raises WebDriverException. It is deprecated in favor of locate_with and emits a DeprecationWarning.

Source

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

def with_tag_name(tag_name: str) -> "RelativeBy":
    """Start searching for relative objects using a tag name.

    Args:
        tag_name: The DOM tag of element to start searching.

    Returns:
        RelativeBy: Use this object to create filters within a `find_elements` call.

    Raises:
        WebDriverException: If `tag_name` is None.

    Note:
        This method is deprecated and may be removed in future versions.
        Please use `locate_with` instead.
    """
    warnings.warn("This method is deprecated and may be removed in future versions. Please use `locate_with` instead.")
    if not tag_name:
        raise WebDriverException("tag_name can not be null")
    return RelativeBy({By.CSS_SELECTOR: tag_name})


def locate_with(by: ByType, using: str) -> "RelativeBy":
    """Start searching for relative objects your search criteria with By.

    Args:
        by: The method to find the element.
        using: The value from `By` passed in.

    Returns:
        RelativeBy: Use this object to create filters within a `find_elements` call.

    Example:
        >>> lowest = driver.find_element(By.ID, "below")
        >>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
    """
    assert by is not None, "Please pass in a by argument"

View on GitHub (pinned to aa36b38e69)

Solutions

1. Migrate to locate_with(By, using) which is the supported, non-deprecated API.
2. If you must use locate(), provide a non-empty tag_name.
3. Address the DeprecationWarning rather than silencing it.

Example fix

# before
from selenium.webdriver.support.relative_locator import locate
elements = driver.find_elements(locate(tag_name="p"))

# after
from selenium.webdriver.common.by import By
from selenium.webdriver.support.relative_locator import locate_with
elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p"))

if not tag_name:
    raise WebDriverException("tag_name can not be null")
# better: switch to locate_with(By, using)

When it happens

Trigger: Calling locate(tag_name=None) or locate(''), typically carried over from old tutorials/code.

Common situations: Legacy code or copied examples still using locate() instead of locate_with().

Related errors

• Port number must be in the range 1..65535
• Element or locator must be given when calling above method
• Element or locator must be given when calling below method
• Element or locator must be given when calling to_left_of met
• Element or locator must be given when calling to_right_of me

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