SeleniumHQ/selenium · warning · KeyError

browserName not specified in session capabilities

Error message

browserName not specified in session capabilities

What it means

Raised by the `name` property when `self.caps` (the session capabilities dict) has no `'browserName'` key. The property is meant to return the browser name, so an absent key is a hard failure surfaced as KeyError. Typically this indicates the session was created against a backend that did not report a browserName in capabilities.

Source

Thrown at py/selenium/webdriver/remote/webdriver.py:362

        if not isinstance(self.file_detector, file_detector_class):
            last_detector = self.file_detector
            self.file_detector = file_detector_class(*args, **kwargs)
        try:
            yield
        finally:
            if last_detector:
                self.file_detector = last_detector

    @property
    def mobile(self) -> Mobile:
        return self._mobile

    @property
    def name(self) -> str:
        """Returns the name of the underlying browser for this instance."""
        if "browserName" in self.caps:
            return self.caps["browserName"]
        raise KeyError("browserName not specified in session capabilities")

    def start_client(self) -> None:
        """Called before starting a new session.

        This method may be overridden to define custom startup behavior.
        """
        pass

    def stop_client(self) -> None:
        """Called after executing a quit command.

        This method may be overridden to define custom shutdown
        behavior.
        """
        pass

    def start_session(self, capabilities: dict) -> None:
        """Creates a new session with the desired capabilities.

View on GitHub (pinned to aa36b38e69)

Solutions

1. Ensure the remote/Grid node advertises browserName in session capabilities.
2. Provide browserName in the Options you pass (e.g. opts.browser_name / set via the browser-specific Options).
3. Don't rely on driver.name when the backend is not a standard browser; read caps.get('browserName') defensively instead.

Example fix

# before
name = driver.name  # KeyError if browserName absent

# after
name = driver.caps.get('browserName', 'unknown')

name = driver.caps.get('browserName')
if name is None:
    # backend didn't report browserName; read caps defensively

try:
    name = driver.name
except KeyError:
    name = driver.caps.get('browserName', 'unknown')

When it happens

Trigger: Reading driver.name on a session that connected to a Selenium Grid routing to an opaque/driverless backend, a custom Appium/remote endpoint, or a misconfigured node that omitted browserName from the returned caps.

Common situations: Grid nodes with incomplete capability configs; drivers created with hand-built capabilities that omit browserName; older remote ends or cloud providers that return sparse caps.

Related errors

• Params must be an instance of CookieFilter. Received:'${cook
• no capabilities provided for merge
• Capability keys must be strings: ${typeof key}
• Downloads must be enabled in options
• Strategy can only be one of the following: normal, eager, no

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