{"record":{"id":"bc3881e2e7f1c889","repo":"SeleniumHQ/selenium","slug":"command-executor-must-be-a-remoteconnection-instan","errorCode":null,"errorMessage":"command_executor must be a RemoteConnection instance for CDP support","messagePattern":"command_executor must be a RemoteConnection instance for CDP support","errorType":"exception","errorClass":"WebDriverException","httpStatus":null,"severity":"error","filePath":"py/selenium/webdriver/remote/webdriver.py","lineNumber":1168,"sourceCode":"            if cdp_version is None:\n                raise WebDriverException(\"CDP version not found in capabilities\")\n            version = cdp_version.split(\".\")[0]\n        else:\n            version, ws_url = self._get_cdp_details()\n\n        if not ws_url:\n            raise WebDriverException(\"Unable to find url to connect to from capabilities\")\n\n        if cdp is None:\n            raise WebDriverException(\"CDP module not loaded\")\n\n        self._devtools = cdp.import_devtools(version)\n        if self._websocket_connection:\n            return self._devtools, self._websocket_connection\n        if self.caps[\"browserName\"].lower() == \"firefox\":\n            raise RuntimeError(\"CDP support for Firefox has been removed. Please switch to WebDriver BiDi.\")\n        if not isinstance(self.command_executor, RemoteConnection):\n            raise WebDriverException(\"command_executor must be a RemoteConnection instance for CDP support\")\n        self._websocket_connection = WebSocketConnection(\n            ws_url,\n            self.command_executor.client_config.websocket_timeout,\n            self.command_executor.client_config.websocket_interval,\n        )\n        targets = self._websocket_connection.execute(self._devtools.target.get_targets())\n        for target in targets:\n            if target.target_id == self.current_window_handle:\n                target_id = target.target_id\n                break\n        session = self._websocket_connection.execute(self._devtools.target.attach_to_target(target_id, True))\n        self._websocket_connection.session_id = session\n        return self._devtools, self._websocket_connection\n\n    @asynccontextmanager\n    async def bidi_connection(self):\n        if self.caps[\"browserName\"].lower() == \"firefox\":\n            raise RuntimeError(\"CDP support for Firefox has been removed. Please switch to WebDriver BiDi.\")","sourceCodeStart":1150,"sourceCodeEnd":1186,"githubUrl":"https://github.com/SeleniumHQ/selenium/blob/aa36b38e696a0909e973bdf5e2f9031ffe842c4b/py/selenium/webdriver/remote/webdriver.py#L1150-L1186","documentation":"Raised by start_devtools() when self.command_executor is not an instance of RemoteConnection. The CDP path needs the executor's client_config (websocket_timeout, websocket_interval) to construct the WebSocketConnection, which only exists on RemoteConnection. A custom or mocked executor that lacks client_config cannot supply these.","triggerScenarios":"Constructing a driver with a custom command_executor object (not RemoteConnection) and then calling start_devtools(). Common when subclassing WebDriver to inject a test executor or a custom HTTP transport.","commonSituations":"Unit tests that inject a fake executor, or custom WebDriver subclasses used for recording/replaying traffic. Also when someone passes a bare HttpConnection or a third-party executor.","solutions":["Use selenium.webdriver.remote.remote_connection.RemoteConnection (or a subclass) as the command_executor.","If you must use a custom executor, subclass RemoteConnection so isinstance passes and expose client_config.","For CDP features specifically, prefer a real RemoteConnection rather than a mock."],"exampleFix":"# before\ndriver = webdriver.Remote(command_executor=MyCustomExecutor(...))\ndriver.start_devtools()\n\n# after\nfrom selenium.webdriver.remote.remote_connection import RemoteConnection\ndriver = webdriver.Remote(command_executor=RemoteConnection(remote_url))\ndriver.start_devtools()","handlingStrategy":"type-guard","validationCode":"from selenium.webdriver.remote.remote_connection import RemoteConnection\nif not isinstance(driver.command_executor, RemoteConnection):\n    raise TypeError('CDP requires a RemoteConnection executor')\ndriver.start_devtools()","typeGuard":"from selenium.webdriver.remote.remote_connection import RemoteConnection\ndef has_remote_connection(driver) -> bool:\n    return isinstance(driver.command_executor, RemoteConnection)","tryCatchPattern":"from selenium.common.exceptions import WebDriverException\ntry:\n    driver.start_devtools()\nexcept WebDriverException as e:\n    if 'RemoteConnection' in str(e):\n        # recreate driver with a RemoteConnection executor\n        raise","preventionTips":["Always pass a RemoteConnection (or subclass) as command_executor.","Subclass RemoteConnection for custom transports rather than replacing it.","Avoid mocks for the executor when exercising CDP code paths."],"tags":["cdp","devtools","remote-connection","executor"],"backgroundTag":null,"analyzedSha":"aa36b38e696a0909e973bdf5e2f9031ffe842c4b","analyzedAt":"2026-08-14T02:32:32.244Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}