SeleniumHQ/selenium · error · WebDriverException

command_executor must be a RemoteConnection instance for BiD

Error message

command_executor must be a RemoteConnection instance for BiDi support

What it means

Raised by _start_bidi() when self.command_executor is not a RemoteConnection instance. The BiDi startup reads client_config.websocket_timeout and websocket_interval from the executor to construct the WebSocketConnection; a non-RemoteConnection executor lacks this attribute. This is the BiDi analogue of the CDP executor-type guard.

Source

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

    @property
    def script(self) -> Script:
        if not self._websocket_connection:
            self._start_bidi()

        if not self._script:
            self._script = Script(self._websocket_connection, self)

        return self._script

    def _start_bidi(self) -> None:
        if self.caps.get("webSocketUrl"):
            ws_url = self.caps.get("webSocketUrl")
        else:
            raise WebDriverException("Unable to find url to connect to from capabilities")

        if not isinstance(self.command_executor, RemoteConnection):
            raise WebDriverException("command_executor must be a RemoteConnection instance for BiDi support")

        self._websocket_connection = WebSocketConnection(
            ws_url,
            self.command_executor.client_config.websocket_timeout,
            self.command_executor.client_config.websocket_interval,
        )

    @property
    def network(self) -> Network:
        if not self._websocket_connection:
            self._start_bidi()

        assert self._websocket_connection is not None
        if not hasattr(self, "_network") or self._network is None:
            assert self._websocket_connection is not None
            self._network = Network(self._websocket_connection)

        return self._network

View on GitHub (pinned to aa36b38e69)

Solutions

1. Use RemoteConnection (or a subclass exposing client_config) as the command_executor.
2. If you subclass the executor, inherit from RemoteConnection so isinstance holds.
3. Avoid BiDi features when running against a non-standard executor.

Example fix

# before
driver = webdriver.Remote(command_executor=FakeExecutor(...))
driver.script  # raises

# after
from selenium.webdriver.remote.remote_connection import RemoteConnection
driver = webdriver.Remote(command_executor=RemoteConnection(url, websocket_timeout=60))

from selenium.webdriver.remote.remote_connection import RemoteConnection
if not isinstance(driver.command_executor, RemoteConnection):
    raise TypeError('BiDi requires a RemoteConnection executor')
driver.script

from selenium.webdriver.remote.remote_connection import RemoteConnection
def has_remote_connection(driver) -> bool:
    return isinstance(driver.command_executor, RemoteConnection)

from selenium.common.exceptions import WebDriverException
try:
    driver.script
except WebDriverException as e:
    if 'RemoteConnection' in str(e):
        raise

When it happens

Trigger: Building a driver with a custom/mock command_executor that is not a RemoteConnection, then accessing driver.script or driver.network (which lazily call _start_bidi).

Common situations: Test harnesses injecting a fake executor, custom WebDriver subclasses, or third-party transports that do not extend RemoteConnection.

Related errors

• command_executor must be a RemoteConnection instance for CDP
• Pattern must be an instance of UrlPattern. Received: '${patt
• Pattern must be an instance of UrlPattern. Received:'${patte
• Pattern must be an instance of String. Received:'${pattern}'
• Pass in a CaptureScreenshotParameters object. Received: ${ca

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