SeleniumHQ/selenium · error · WebDriverException

CDP module not loaded

Error message

CDP module not loaded

What it means

Raised by start_devtools() when the global cdp module is still None after import_cdp() was called. The CDP bindings are an optional dependency shipped as a separate module; if importing them failed silently or they are absent, Selenium cannot translate DevTools commands. This guard prevents a confusing AttributeError later.

Source

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

            raise WebDriverException("You can only set the orientation to 'LANDSCAPE' and 'PORTRAIT'")

    def start_devtools(self) -> tuple[Any, WebSocketConnection]:
        global cdp
        import_cdp()
        if self.caps.get("se:cdp"):
            ws_url = self.caps.get("se:cdp")
            cdp_version = self.caps.get("se:cdpVersion")
            if cdp_version is None:
                raise WebDriverException("CDP version not found in capabilities")
            version = cdp_version.split(".")[0]
        else:
            version, ws_url = self._get_cdp_details()

        if not ws_url:
            raise WebDriverException("Unable to find url to connect to from capabilities")

        if cdp is None:
            raise WebDriverException("CDP module not loaded")

        self._devtools = cdp.import_devtools(version)
        if self._websocket_connection:
            return self._devtools, self._websocket_connection
        if self.caps["browserName"].lower() == "firefox":
            raise RuntimeError("CDP support for Firefox has been removed. Please switch to WebDriver BiDi.")
        if not isinstance(self.command_executor, RemoteConnection):
            raise WebDriverException("command_executor must be a RemoteConnection instance for CDP support")
        self._websocket_connection = WebSocketConnection(
            ws_url,
            self.command_executor.client_config.websocket_timeout,
            self.command_executor.client_config.websocket_interval,
        )
        targets = self._websocket_connection.execute(self._devtools.target.get_targets())
        for target in targets:
            if target.target_id == self.current_window_handle:
                target_id = target.target_id
                break

View on GitHub (pinned to aa36b38e69)

Solutions

  1. Reinstall Selenium cleanly: pip install --force-reinstall selenium.
  2. Verify the import works in isolation: python -c 'from selenium.webdriver.common.bidi import import_cdp; import_cdp(); from selenium.webdriver import remote; print(remote.cdp)'.
  3. Check for conflicting selenium installs on sys.path (pip show selenium, and look for multiple installs).
Defensive patterns

Strategy: try-catch

Validate before calling

# Verify CDP import works before using it
from selenium.webdriver.common.bidi import import_cdp
import_cdp()
from selenium.webdriver.remote import webdriver as _w
if _w.cdp is None:
    raise RuntimeError('CDP module failed to import; reinstall selenium')

Try / catch

from selenium.common.exceptions import WebDriverException
try:
    devtools, conn = driver.start_devtools()
except WebDriverException as e:
    if 'CDP module not loaded' in str(e):
        import subprocess; subprocess.run(['pip', 'install', '--force-reinstall', 'selenium'])

Prevention

When it happens

Trigger: The bundled CDP module failed to import (missing dependencies, corrupted install, partial Selenium installation) so import_cdp() did not populate the global cdp. Then start_devtools() proceeds past the URL checks and hits this guard.

Common situations: A broken or partial Selenium install (e.g. manually deleted the cdp subpackage), an environment where the CDP module's transitive dependencies are missing, or a custom packaging that excludes the devtools bindings.

Related errors

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